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)

{
  "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)

{
  "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

-- 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

# 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

-- 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

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

cd frontend

# Installation des dépendances Flutter
flutter pub get

# Build pour production
flutter build web --release

---

Variables d'Environnement

Backend (.env)

# 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

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

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

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

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

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

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

   # 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

   # 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

   # 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

   # 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)

   sudo apt install fail2ban
   sudo systemctl enable fail2ban
   

2. Monitoring des logs

   # Logrotate pour éviter les gros fichiers
   sudo nano /etc/logrotate.d/ptitspas
   

3. Updates automatiques

   sudo apt install unattended-upgrades
   sudo dpkg-reconfigure unattended-upgrades
   

---

Commandes de Gestion

Démarrage des services

# 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

# 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é

# 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

   # 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

   # Vérifier build
   cd frontend && flutter build web
   
   # Vérifier nginx
   sudo nginx -t
   sudo systemctl reload nginx
   

3. Erreurs base de données

   # 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.