petitspas/docs/ARCHITECTURE_TECHNIQUE.md

# Architecture Technique - P'titsPas
## Guide d'Infrastructure et de Déploiement

---

## Vue d'ensemble

P'titsPas est une application de gestion de garde d'enfants pour les collectivités locales, basée sur une architecture **client-serveur moderne** :

- **Frontend** : Application web Flutter (Single Page Application)
- **Backend** : API REST Node.js/Express avec TypeScript
- **Base de données** : PostgreSQL avec ORM Prisma
- **Architecture** : Séparation claire frontend/backend avec API REST

---

## Prérequis Serveur

### Environnement d'exécution

#### Backend
- **Node.js** : Version 18+ (LTS recommandée : 18.19.0+)
- **npm** : Version 9+
- **TypeScript** : Inclus dans les dépendances du projet

#### Base de données
- **PostgreSQL** : Version 15+ 
- **Extensions** : UUID (pour les clés primaires)

#### Frontend
- **Serveur web statique** : nginx, Apache, ou similaire
- **Flutter Web** : Compilation en JavaScript (pas de prérequis runtime)

### Ressources recommandées

#### Environnement de développement
- **RAM** : 4GB minimum
- **CPU** : 2 vCPU
- **Storage** : 10GB

#### Environnement de production
- **RAM** : 8GB recommandé (4GB minimum)
- **CPU** : 4 vCPU recommandé (2 vCPU minimum)
- **Storage** : 50GB minimum (base de données + logs + backups)
- **Réseau** : 
  - Port 3000 : API Backend (interne)
  - Port 80/443 : Web (externe)
  - Port 5432 : PostgreSQL (interne uniquement)

---

## Stack Technique Détaillée

### Backend (API)

```json
{
  "runtime": "Node.js 18+",
  "language": "TypeScript",
  "framework": "Express.js 4.18+",
  "orm": "Prisma 6.7+",
  "database_client": "@prisma/client",
  "security": [
    "helmet (sécurité headers)",
    "cors (CORS policy)",
    "bcrypt (hashage mots de passe)",
    "jsonwebtoken (JWT auth)"
  ],
  "logging": "morgan",
  "validation": "@nestjs/common"
}
```

### Frontend (Web)

```json
{
  "framework": "Flutter 3.2.6+",
  "language": "Dart 3.0+",
  "compilation": "JavaScript (Flutter Web)",
  "navigation": "go_router 13.2+",
  "state_management": "provider 6.1+",
  "ui_framework": "Material Design",
  "fonts": "Google Fonts",
  "http_client": "http 1.2+"
}
```

### Base de données

```sql
-- Structure PostgreSQL
-- Tables principales :
-- - Parent (utilisateurs parents)
-- - Child (enfants)
-- - Contract (contrats de garde)
-- - Admin (administrateurs)
-- - Theme (thèmes interface)
-- - AppSettings (paramètres app)

-- Types de données :
-- - UUID pour toutes les clés primaires
-- - Timestamps automatiques (createdAt, updatedAt)
-- - Enums pour les statuts
```

---

## Installation et Configuration

### 1. Prérequis système

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install -y nodejs npm postgresql postgresql-contrib nginx

# Vérification versions
node --version  # >= 18.0.0
npm --version   # >= 9.0.0
psql --version  # >= 15.0
```

### 2. Configuration base de données

```sql
-- Se connecter en tant que postgres
sudo -u postgres psql

-- Créer la base de données et l'utilisateur
CREATE DATABASE ptitspas;
CREATE USER ptitspas_user WITH PASSWORD 'secure_password_here';
GRANT ALL PRIVILEGES ON DATABASE ptitspas TO ptitspas_user;
ALTER USER ptitspas_user CREATEDB; -- Pour les migrations

-- Quitter
\q
```

### 3. Installation Backend

```bash
cd backend

# Installation des dépendances
npm install

# Configuration environnement
cp .env.example .env
# Éditer .env avec vos paramètres

# Génération du client Prisma et migrations
npx prisma generate
npx prisma migrate deploy

# Initialisation admin (optionnel)
npm run init-admin
```

### 4. Installation Frontend

```bash
cd frontend

# Installation des dépendances Flutter
flutter pub get

# Build pour production
flutter build web --release
```

---

## Variables d'Environnement

### Backend (.env)

```bash
# Base de données
DATABASE_URL="postgresql://ptitspas_user:secure_password_here@localhost:5432/ptitspas"

# Sécurité
JWT_SECRET="your-super-secret-jwt-key-minimum-32-characters"
JWT_EXPIRES_IN="24h"

# Serveur
PORT=3000
NODE_ENV=production

# Optionnel
CORS_ORIGIN="https://ptitspas.yourdomain.com"
```

---

## Déploiement

### Option 1 : Déploiement classique (recommandé)

#### Backend

```bash
cd backend

# Installation production
npm ci --only=production

# Build TypeScript
npm run build

# Démarrage (avec PM2 recommandé)
npm install -g pm2
pm2 start dist/index.js --name "ptitspas-api"
pm2 startup
pm2 save
```

#### Frontend

```bash
cd frontend

# Build production
flutter build web --release

# Copier vers serveur web
sudo cp -r build/web/* /var/www/ptitspas/
sudo chown -R www-data:www-data /var/www/ptitspas/
```

### Option 2 : Conteneurisation Docker

#### Dockerfile Backend

```dockerfile
FROM node:18-alpine

# Créer répertoire app
WORKDIR /app

# Copier package files
COPY package*.json ./
COPY prisma ./prisma/

# Installer dépendances
RUN npm ci --only=production

# Copier code source
COPY . .

# Build
RUN npm run build

# Générer client Prisma
RUN npx prisma generate

# Exposer port
EXPOSE 3000

# Variables d'environnement
ENV NODE_ENV=production

# Commande démarrage
CMD ["npm", "start"]
```

#### Dockerfile Frontend

```dockerfile
FROM nginx:alpine

# Copier build Flutter
COPY build/web /usr/share/nginx/html

# Configuration nginx
COPY nginx.conf /etc/nginx/nginx.conf

# Exposer port
EXPOSE 80

# Démarrage nginx
CMD ["nginx", "-g", "daemon off;"]
```

#### Docker Compose

```yaml
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ptitspas
      POSTGRES_USER: ptitspas_user
      POSTGRES_PASSWORD: secure_password_here
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  backend:
    build: ./backend
    environment:
      DATABASE_URL: postgresql://ptitspas_user:secure_password_here@postgres:5432/ptitspas
      JWT_SECRET: your-super-secret-jwt-key
      NODE_ENV: production
    ports:
      - "3000:3000"
    depends_on:
      - postgres

  frontend:
    build: ./frontend
    ports:
      - "80:80"
    depends_on:
      - backend

volumes:
  postgres_data:
```

---

## Configuration Nginx

### Configuration complète

```nginx
server {
    listen 80;
    server_name ptitspas.yourdomain.com;
    
    # Redirection HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name ptitspas.yourdomain.com;

    # Certificats SSL
    ssl_certificate /etc/letsencrypt/live/ptitspas.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ptitspas.yourdomain.com/privkey.pem;
    
    # Configuration SSL sécurisée
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    # Frontend statique (Flutter Web)
    location / {
        root /var/www/ptitspas;
        index index.html;
        try_files $uri $uri/ /index.html;
        
        # Cache statique
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }

    # API Backend
    location /api/ {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        
        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # Logs
    access_log /var/log/nginx/ptitspas_access.log;
    error_log /var/log/nginx/ptitspas_error.log;
}
```

---

## Sécurité

### Obligatoire

1. **HTTPS avec certificat SSL**
   ```bash
   # Installation Certbot
   sudo apt install certbot python3-certbot-nginx
   
   # Génération certificat
   sudo certbot --nginx -d ptitspas.yourdomain.com
   
   # Renouvellement automatique
   sudo crontab -e
   # Ajouter : 0 12 * * * /usr/bin/certbot renew --quiet
   ```

2. **Firewall**
   ```bash
   # UFW (Ubuntu)
   sudo ufw allow 22    # SSH
   sudo ufw allow 80    # HTTP
   sudo ufw allow 443   # HTTPS
   sudo ufw enable
   ```

3. **Base de données sécurisée**
   ```bash
   # PostgreSQL : accès local uniquement
   sudo nano /etc/postgresql/15/main/postgresql.conf
   # Commenter : #listen_addresses = 'localhost'
   
   sudo nano /etc/postgresql/15/main/pg_hba.conf
   # Vérifier que seules les connexions locales sont autorisées
   ```

4. **Backup automatique**
   ```bash
   # Script backup
   #!/bin/bash
   BACKUP_DIR="/var/backups/ptitspas"
   DATE=$(date +%Y%m%d_%H%M%S)
   
   pg_dump -U ptitspas_user -h localhost ptitspas > $BACKUP_DIR/ptitspas_$DATE.sql
   
   # Nettoyer les backups > 30 jours
   find $BACKUP_DIR -name "*.sql" -mtime +30 -delete
   
   # Crontab : tous les jours à 2h
   # 0 2 * * * /path/to/backup_script.sh
   ```

### Recommandé

1. **Fail2Ban** (protection brute force)
   ```bash
   sudo apt install fail2ban
   sudo systemctl enable fail2ban
   ```

2. **Monitoring des logs**
   ```bash
   # Logrotate pour éviter les gros fichiers
   sudo nano /etc/logrotate.d/ptitspas
   ```

3. **Updates automatiques**
   ```bash
   sudo apt install unattended-upgrades
   sudo dpkg-reconfigure unattended-upgrades
   ```

---

## Commandes de Gestion

### Démarrage des services

```bash
# Backend (développement)
cd backend && npm run dev

# Backend (production avec PM2)
pm2 start ptitspas-api
pm2 status

# Base de données
sudo systemctl start postgresql
sudo systemctl status postgresql

# Serveur web
sudo systemctl start nginx
sudo systemctl status nginx
```

### Maintenance

```bash
# Migrations base de données
cd backend
npx prisma migrate deploy

# Logs Backend
pm2 logs ptitspas-api

# Logs Nginx
sudo tail -f /var/log/nginx/ptitspas_access.log
sudo tail -f /var/log/nginx/ptitspas_error.log

# Restart services
pm2 restart ptitspas-api
sudo systemctl restart nginx
```

---

## Monitoring et Healthcheck

### Endpoints de santé

```bash
# API Health (à implémenter)
curl https://ptitspas.yourdomain.com/api/health

# Base de données
psql -h localhost -U ptitspas_user -d ptitspas -c "SELECT 1;"

# Frontend
curl -I https://ptitspas.yourdomain.com/
```

### Logs à surveiller

1. **Backend** : Via PM2 ou logs applicatifs
2. **PostgreSQL** : `/var/log/postgresql/postgresql-15-main.log`
3. **Nginx** : `/var/log/nginx/ptitspas_*.log`
4. **Système** : `/var/log/syslog`

### Métriques importantes

- **CPU/RAM** : Usage serveur
- **Espace disque** : Base de données et logs
- **Connexions DB** : Nombre de connexions actives
- **Temps de réponse** : API et frontend
- **Erreurs 5xx** : Erreurs serveur

---

## Troubleshooting

### Problèmes courants

1. **Backend ne démarre pas**
   ```bash
   # Vérifier variables d'environnement
   cd backend && cat .env
   
   # Vérifier connexion DB
   npx prisma db pull
   
   # Logs détaillés
   npm run dev
   ```

2. **Frontend ne s'affiche pas**
   ```bash
   # Vérifier build
   cd frontend && flutter build web
   
   # Vérifier nginx
   sudo nginx -t
   sudo systemctl reload nginx
   ```

3. **Erreurs base de données**
   ```bash
   # Vérifier statut PostgreSQL
   sudo systemctl status postgresql
   
   # Vérifier connexions
   sudo -u postgres psql -c "SELECT * FROM pg_stat_activity;"
   ```

---

## Évolutivité

### Optimisations possibles

1. **Cache Redis** : Pour les sessions et cache applicatif
2. **CDN** : Pour les assets statiques
3. **Load Balancer** : Pour haute disponibilité
4. **Clustering** : Multiple instances Node.js
5. **Database replication** : Master/Slave PostgreSQL

### Monitoring avancé

- **Prometheus + Grafana** : Métriques système et applicatif
- **ELK Stack** : Centralisation des logs
- **Uptime monitoring** : Surveillance externe

Cette architecture est conçue pour être **scalable**, **maintenable** et **sécurisée** pour un environnement de production professionnel.