Vue d'ensemble

Cette page décrit l'architecture de BlockLucky selon le modèle C4, du plus large au plus détaillé : le contexte (qui utilise le système et avec quels systèmes externes il échange), les conteneurs (les applications et les stockages qui tournent), puis les composants du backend. Les diagrammes sont écrits en Mermaid dans les sources de la documentation : ils se modifient dans la même pull request que le changement d'architecture qu'ils décrivent.

Trois idées structurent l'ensemble :

• La blockchain est la source de vérité de la loterie. Les tickets, le tirage, la cagnotte et les remboursements vivent dans le contrat BlockLucky. La base PostgreSQL en est une projection, reconstruite par un indexeur d'événements.
• Le citoyen n'installe aucun portefeuille. Le backend crée et chiffre un portefeuille Ethereum par citoyen, signe ses transactions et lui verse une dotation d'ethers fictifs (voir l'ADR 0004).
• Un seul backend, deux process. L'API HTTP et le worker sont construits depuis la même image et le même code (voir l'ADR 0001).

#Niveau 1 : contexte

flowchart LR
  citoyen(["Citoyen d'EtherBay"])
  commercant(["Commerçant partenaire"])
  mairie(["Mairie et DSI"])
  visiteur(["Visiteur"])

  blocklucky[["BlockLucky : loterie citoyenne et fidélité"]]
  tourisme[["Site de l'Office de Tourisme"]]

  ethereum[("Réseau Ethereum : Hardhat local ou Sepolia")]
  vrf[("Chainlink VRF v2.5")]
  smtp[("Serveur SMTP")]
  s3[("Stockage objet S3")]

  citoyen -->|"achète et offre des tickets, échange ses EtherPoints"| blocklucky
  commercant -->|"publie des offres, valide des codes"| blocklucky
  mairie -->|"pilote tirage, disjoncteur, trésorerie, rapports"| blocklucky
  visiteur -->|"prépare son séjour"| tourisme
  tourisme -.->|"liens vers la loterie"| blocklucky
  blocklucky -->|"transactions signées, lecture des événements"| ethereum
  ethereum <-->|"demande et preuve d'aléa"| vrf
  blocklucky -->|"emails transactionnels"| smtp
  blocklucky -->|"rapports comptables"| s3

#Acteurs

Les rôles sont l'énumération Role de backend/prisma/schema.prisma, contrôlés par requireRoles dans backend/src/middlewares/rbac.middleware.ts. Le détail des droits est dans la matrice des autorisations.

#Systèmes externes

#Niveau 2 : conteneurs

flowchart TB
  subgraph clients["Clients"]
    web["frontend-web : Next.js 16"]
    mobile["mobile-app : Expo et React Native"]
    office["frontend-office-tourisme : HTML statique"]
  end

  subgraph backend["backend : même image"]
    api["API : Express 5, REST /api/v1, Socket.IO"]
    worker["Worker : BullMQ, indexeur, keeper"]
  end

  pg[("PostgreSQL 15")]
  redis[("Redis 7")]
  smtp[("Mailpit ou SMTP")]
  rpc[("Nœud RPC Ethereum")]
  contracts[["BlockLucky et BlockLuckyPOAP"]]
  vrf[("Coordinateur VRF")]

  web -->|"HTTPS JSON, WebSocket"| api
  mobile -->|"HTTPS JSON, WebSocket"| api
  office -.->|"liens"| web
  api -->|"Prisma, pool pg"| pg
  api -->|"ioredis"| redis
  worker -->|"Prisma"| pg
  worker -->|"jobs, verrous, pub/sub"| redis
  worker -->|"SMTP"| smtp
  api -->|"ethers v6"| rpc
  worker -->|"ethers v6"| rpc
  rpc --- contracts
  contracts <--> vrf
  redis -.->|"événements temps réel"| api

#Répartition entre l'API et le worker

Le process API (backend/src/server.ts) démarre Express, Socket.IO et le pont d'événements Redis. Il ne démarre les workers BullMQ et les services de chaîne (indexeur et keeper) que si RUN_WORKERS=true, la valeur par défaut du schéma de configuration. Docker Compose fixe RUN_WORKERS: "false" pour le service backend et lance un service worker séparé.

Le process worker (backend/src/worker.ts) démarre toujours startWorkers() et startChainServices(). Il s'arrête avec un code d'erreur si aucun worker n'a pu être créé, et expose /health/live et /metrics sur le port PORT + 1.

L'indexeur et le keeper sont démarrés par startChainServices dans backend/src/blockchain/lottery.keeper.ts. Ils ne font rien en mode simulated. Le détail est dans Indexeur d'événements et Keeper du tirage.

#Relais des événements temps réel

Les événements draw:winner et points:awarded sont produits par l'indexeur, donc souvent dans le worker, qui n'a pas de serveur Socket.IO. emitSocketEvent (backend/src/socket/event-bridge.ts) émet directement si le process possède un serveur Socket.IO, sinon publie le message sur le canal Redis <REDIS_KEY_PREFIX>:<NODE_ENV>:socket-events. L'API s'y abonne au démarrage (startSocketEventBridge) et réémet vers tous les clients connectés, en ne laissant passer que ces deux événements. Voir Relais temps réel.

#Modes de fonctionnement

BLOCKCHAIN_MODE (backend/src/config/env.config.ts) vaut onchain par défaut et est imposé en production par le schéma Zod. En mode simulated, les services de backend/src/services/blockchain.service.ts génèrent des hash aléatoires, tirent le gagnant avec crypto.randomInt et ne versent aucune cagnotte. Ce mode sert aux tests unitaires et au développement sans nœud. Voir Mode onchain ou simulé.

#Niveau 3 : composants du backend

flowchart TB
  subgraph http["Chaîne HTTP : app.ts"]
    mw["Middlewares transverses"]
    routes["Modules api/domaine : routes, controllers, services, repo"]
    err["error.middleware"]
  end

  subgraph transverse["Services transverses"]
    ledger["ledger.service"]
    session["session.service et otp-challenge.service"]
    mail["emails.queue et email.service"]
  end

  subgraph chain["blockchain/"]
    gateway["lottery.gateway"]
    wallet["wallet.service"]
    indexer["lottery.indexer"]
    keeper["lottery.keeper"]
    actions["chain-actions"]
    client["chain.client"]
  end

  socket["socket/ : handler et event-bridge"]
  prisma[("prisma.config")]
  redis[("redis.config")]

  mw --> routes --> err
  routes --> ledger
  routes --> session
  routes --> mail
  routes --> gateway
  gateway --> wallet
  gateway --> indexer
  keeper --> indexer
  indexer --> actions
  indexer --> ledger
  indexer --> socket
  gateway --> client
  actions --> client
  ledger --> prisma
  routes --> redis

#Chaîne HTTP

backend/src/app.ts monte les middlewares dans cet ordre :

1. requestContextMiddleware : identifiant X-Request-Id propagé dans les logs par AsyncLocalStorage (backend/src/observability/request-context.ts).
2. httpMetricsMiddleware : histogrammes Prometheus par route (backend/src/observability/metrics.ts).
3. Helmet, CORS limité à FRONTEND_URL et CORS_ORIGINS, express.json limité à 1 Mo (corps brut conservé pour /api/webhooks/*), express.urlencoded.
4. Routes système (/health, /health/live, /health/ready, /health/deep, /api/config) et /metrics, avant le mode maintenance et le rate limit.
5. Mode maintenance : MAINTENANCE_MODE=true renvoie 503 avec Retry-After: 300 sur /api/* sauf /api/admin.
6. globalRateLimiter : 300 requêtes par 15 minutes et par IP, compteurs dans Redis.
7. Swagger sur /api/docs, puis le routeur des modules monté sur /api/v1 et /api.
8. notFoundHandler et errorHandler.

Dans chaque route, les middlewares spécifiques suivent l'ordre authenticate, requireRoles, idempotency, validate, puis le controller. Le détail est dans Structure et cycle d'une requête.

#Modules métier

#Composants transverses

#Composants blockchain

#Où trouver la suite

• Le rôle de chaque dossier : Organisation du dépôt.
• Les raisons des choix de briques : Choix techniques et les décisions d'architecture.
• Le déroulé précis des cas d'usage : Flux métier.
• Le déploiement des conteneurs : Docker Compose.