# 04 — Architecture technique

## Vue d'ensemble

```
                          Internet (HTTPS)
                                │
                        ┌───────▼────────┐
                        │    Apache2     │  vhost leperelion.fr (:80 → :443)
                        │ reverse proxy  │  SSL Let's Encrypt
                        └───┬────────┬───┘
              /backend/*    │        │   /  (+ ws hot-reload)
                            │        │
                  ┌─────────▼──┐  ┌──▼──────────┐
                  │  Backend    │  │  Frontend   │
                  │ Express 5   │  │  Next.js 16 │
                  │ :4002       │  │  :3002      │
                  │ (PM2)       │  │  (PM2)      │
                  └──────┬──────┘  └─────────────┘
                         │ Prisma (adapter-pg)
                  ┌──────▼──────┐
                  │ PostgreSQL  │  base `leperelion` (:5432)
                  └─────────────┘
                         ▲
                         │ OAuth 2.0 / REST
                  ┌──────┴──────┐
                  │ Google APIs │  Calendar, Gmail (+ futurs)
                  └─────────────┘
```

## Choix structurants

- **Même stack que les autres sites** (Next.js / Express / Prisma / PostgreSQL / PM2 / Apache)
  pour homogénéité et maintenance — décidé avec l'utilisateur.
- **Ports dédiés** : frontend **3002**, backend **4002** (3000/3001/4000/4001 déjà pris).
- **Reverse proxy Apache** : le frontend appelle l'API en **même origine** via `/backend/*`
  (comme woogalf), ce qui évite les soucis CORS en prod.

## Backend (`/backend`)

- **Express 5 + TypeScript**, compilé via `tsc` vers `dist/`, lancé par PM2 (`node dist/index.js`).
- **Prisma 7** avec `@prisma/adapter-pg` et le driver `pg` (même version que woogalf).
- Organisation suggérée :
  ```
  backend/src/
    index.ts            # bootstrap express
    config/             # env, constantes
    middleware/         # auth JWT, gestion erreurs
    modules/
      auth/             # login, register, refresh
      google/           # OAuth, refresh tokens, clients API
      calendar/         # endpoints agenda
      mail/             # endpoints Gmail
      location/         # endpoints position
    lib/                # crypto (chiffrement tokens), logger, prisma client
  ```
- **Auth** : JWT access + refresh en cookies httpOnly. Hash mots de passe bcrypt.
- **Sécurité** : helmet/CORS au besoin, tokens Google chiffrés au repos (AES-GCM via
  `LEPERELION_ENCRYPTION_KEY`).

## Frontend (`/frontend`)

- **Next.js 16 (App Router) + React 19 + Tailwind 4 + TypeScript**.
- Appelle le backend via `/backend/*` (proxifié par Apache en prod).
- **Mobile-first impératif** : design pensé d'abord pour mobile, variantes `sm:`/`md:`/`lg:`
  ajoutées ensuite pour le desktop.
- **Navigation = sidebar gauche** : tiroir coulissant sur mobile (bouton ☰ + voile), fixe à
  partir de `md`. Layout authentifié dans `app/(app)/` : `layout.tsx` (auth + provider user +
  shell), `Sidebar.tsx`, `user-context.tsx`. La page de connexion `/` reste hors layout.
- Pages/sections : Connexion (`/`), puis sous le shell : Tableau de bord, (Agenda, Mail à venir),
  Mon profil, Gestion des comptes (super_admin).

## Intégration Google

- Détaillée dans [05_INTEGRATION_GOOGLE.md](05_INTEGRATION_GOOGLE.md) (OAuth, scopes, stockage).
- Lib `googleapis` côté backend ; le frontend ne manipule jamais les tokens Google directement.

## Suivi de position

- Approche pressentie (à valider) : composant web/PWA sur le téléphone qui POST sa position
  vers `/backend/location`. Stockage des points en base, affichage carte côté frontend
  (lib carto à choisir : Leaflet/OSM ou Google Maps JS — voir questions restantes).

## Données & migrations

- Modèle détaillé dans [06_MODELE_DONNEES.md](06_MODELE_DONNEES.md).
- Migrations gérées par **Prisma Migrate** ; le rôle `leperelion` a l'attribut `CREATEDB`
  pour permettre la *shadow database* Prisma en dev — **isolé**, sans impact sur les autres bases.

## Déploiement

- Voir [07_DEPLOIEMENT_INFRA.md](07_DEPLOIEMENT_INFRA.md) (vhost, PM2, SSL, variables d'env).