Architecture & Guide technique

🏛️ Vue d'ensemble

Présentation

UrbaFood est une plateforme municipale de livraison alimentaire conçue pour soutenir l'économie locale. Contrairement aux plateformes commerciales (Uber Eats, Deliveroo…) qui prélèvent 25–30% de commission, UrbaFood prélève 1% seulement, uniquement pour couvrir les frais de maintenance.

Objectifs

Stack technique

🏗️ Architecture système

Infrastructure

L'architecture suit un modèle en couches avec HAProxy comme point d'entrée unique, délégant vers Nginx qui route vers le backend ou le frontend selon le chemin de la requête.

Internet (HTTPS :443)
    ↓  SSL termination
HAProxy  (/srv/haproxy)
    ↓  HTTP interne  (réseau: urbafood_network)
Nginx  (urbafood_web:80)
    ├─ /api/*             →  Backend NestJS        (urbafood_backend:3000)
    ├─ /coursier-app/*    →  PWA Coursiers React   (urbafood_coursiers:80)
    └─ /*                 →  Frontend Next.js       (urbafood_frontend:3001)

Backend NestJS
    ├─ TypeORM  →  MariaDB  (urbafood_mariadb:3306)
    ├─ Redis    →  Cache / Queue  (urbafood_redis:6379)
    └─ Worker   →  BullMQ processors (urbafood_worker)

Services Docker

Réseau

🗄️ Base de données

Schéma

MariaDB 11.5, moteur InnoDB, charset UTF8MB4 (support émojis), timestamps UTC, soft deletes sur toutes les tables (deleted_at).

Tables

Diagramme ERD

🔌 API REST

Base URL : https://urbafood.me/api — Documentation Swagger interactive : https://urbafood.me/api/docs

Authentification

Restaurants

Plats

Commandes

Google Business Profile

Ces endpoints permettent à un restaurateur de connecter et synchroniser sa fiche Google Business Profile avec son restaurant UrbaFood. L'OAuth Google est géré côté backend — aucun secret n'est exposé au frontend.

Coursiers

Tous les endpoints coursiers nécessitent un token JWT valide (role: COURIER recommandé). Le profil coursier est créé juste après l'inscription via POST /couriers/register.

📖 API Reference (Swagger)

L'interface Swagger UI générée automatiquement par NestJS documente l'intégralité des endpoints disponibles, avec schémas de requête/réponse, codes d'erreur et possibilité de tester chaque route directement depuis le navigateur.

Interface interactive

Utilisation rapide

Lien direct en plein écran : https://urbafood.me/api/docs ↗

🔐 Authentification

JWT Flow

Le système utilise deux tokens : un access token (15 min) pour les requêtes API, et un refresh token (7 jours) pour renouveler l'accès sans re-authentification. Le renouvellement est automatique et transparent côté frontend — lib/api.ts intercepte les 401, appelle POST /auth/refresh, puis rejoue la requête initiale.

// Payload JWT
{
  "sub": 1,               // user.id
  "email": "user@ex.fr",
  "role": "RESTAURANT",
  "iat": 1234567890,
  "exp": 1234568790       // +15min
}

Rôles & permissions

🔄 Flux fonctionnels

Cycle de vie d'une commande

Parcours restaurateur

1. Inscription → /login (role: RESTAURANT)
2. Créer restaurant → /restaurant/profil
   └─ En attente validation municipale (is_validated: false)
3. Ajouter menu → /restaurant/menu
   └─ Plats groupés par catégorie
   └─ Toggle disponibilité en temps réel
4. Traiter commandes → /restaurant/commandes
   └─ pending → confirmer → préparer → prêt
5. Suivre revenus → /restaurant/statistiques
   └─ CA brut, commission 1%, net, panier moyen

Parcours coursier

1. Découverte → /rejoindre-coursier (page marketing)
2. Inscription → /login?mode=register&role=COURIER   (Next.js)
              ou directement sur https://urbafood.me/coursier-app/  (PWA)
   └─ Sélection du véhicule (vélo, scooter, voiture)
   └─ POST /couriers/register appelé automatiquement
   └─ Redirection vers /coursier  (Next.js)  ou /  (PWA)
3. Dashboard → /coursier  (Next.js)  |  /coursier-app/  (PWA)
   └─ Toggle disponible / hors ligne (PATCH /couriers/availability)
   └─ Stats du jour : livraisons, gains, note
   └─ Aperçu des livraisons disponibles (3 premières)
4. Accepter une livraison → /coursier/livraisons  |  /coursier-app/livraisons
   └─ GET /couriers/orders/available (statut READY, courier_id IS NULL)
   └─ POST /couriers/orders/:id/accept
      → courier_id = courseId, status → picked_up, picked_up_at = NOW()
      → 409 si le coursier a déjà une livraison active
5. Suivre la livraison → /coursier/en-cours  |  /coursier-app/en-cours
   └─ Timeline : récupération au restaurant → livraison en cours
   └─ POST /couriers/orders/:id/deliver
      → status → delivered, delivered_at = NOW(), totalDeliveries++
6. Consulter les gains → /coursier/gains  |  /coursier-app/gains
   └─ Filtre aujourd'hui / 7 jours / 30 jours
   └─ 100 % des frais de livraison reversés au coursier
7. Gérer le profil → /coursier/profil  |  /coursier-app/profil
   └─ Modifier véhicule, plaque
   └─ Voir note moyenne, total livraisons

🖥️ Frontend

Pages & routes

Système de design

📱 PWA Coursiers

Présentation

La PWA Coursiers est une application Progressive Web App installable sur Android et iOS, accessible à https://urbafood.me/coursier-app/. Elle offre une expérience native — plein écran sans barre Chrome, icône sur l'écran d'accueil, fonctionnement partiel hors-ligne — tout en étant une application web standard.

Installation Android / iOS

Android (Chrome) :

1. Ouvrir https://urbafood.me/coursier-app/ dans Chrome Android
2. Se connecter avec un compte COURIER
3. Chrome affiche automatiquement le bandeau "Installer l'application"
4. Ou : menu ⋮ → "Installer l'application" / "Ajouter à l'écran d'accueil"
5. L'icône UrbaFood Coursier apparaît sur l'écran d'accueil
6. Au lancement : mode plein écran sans barre de navigation Chrome

Critères d'installabilité (Chrome Android) :

Stack & architecture

Comportement hors-ligne :

Auth JWT : même système que le frontend principal — uf_token (15 min), uf_refresh_token (7 j), refresh automatique sur 401 dans src/api.ts.

Déploiement

# 1. Build de l'image Docker (depuis /srv/urbafood/)
docker build \
  --build-arg VITE_API_URL=https://urbafood.me/api \
  --build-arg VITE_BASE=/coursier-app/ \
  -t urbafood-coursiers \
  ./coursiers/

# 2. Lancer le service
docker-compose up -d coursiers
docker-compose restart nginx

# 3. Vérifier
curl https://urbafood.me/coursier-app/
curl https://urbafood.me/coursier-app/manifest.webmanifest
curl https://urbafood.me/coursier-app/sw.js

Développement local avec ngrok (test PWA sur Android) :

cd apps/coursiers
npm install
npm run dev -- --host          # Terminal 1 — accessible sur LAN

npx ngrok http 5173            # Terminal 2 — tunnel HTTPS
# → https://xxxx.ngrok-free.app

# Sur Chrome Android : ouvrir l'URL ngrok → menu ⋮ → Installer

⚙️ Exploitation

Déploiement

# Depuis /srv/urbafood

# Rebuild après modification du code source
docker-compose build backend frontend
docker-compose up -d --force-recreate backend frontend

# Rebuild complet (sans cache)
docker-compose build --no-cache backend
docker-compose up -d

# Vérifier l'état
docker-compose ps
docker-compose logs -f backend --tail=50

SSL & HAProxy

Le certificat Let's Encrypt est géré par HAProxy. Il expire le 17 mai 2026 (renouvellement automatique configuré par certbot).

# Renouvellement manuel si nécessaire
cd /srv/haproxy && docker-compose stop
sudo certbot certonly --standalone -d urbafood.me -d www.urbafood.me
sudo cat /etc/letsencrypt/live/urbafood.me/fullchain.pem \
         /etc/letsencrypt/live/urbafood.me/privkey.pem \
         > /srv/haproxy/certs/urbafood.pem
cd /srv/haproxy && docker-compose up -d

Logs & monitoring

📋 Changelog