BlockLucky Documentation officielle GitHub
16. Annexes

Index des fichiers clés

Les fichiers à lire en premier dans chaque projet, avec leur rôle. Ils suffisent pour comprendre le fonctionnement d'ensemble avant d'entrer dans un module. L'organisation complète du dépôt est décrite dans Organisation du dépôt.

Racine du dépôt

Fichier Rôle
docker-compose.yml Infrastructure locale et stack complète (profil app), voir Docker Compose
docker/postgres/init/01-extensions.sql Création de pg_stat_statements à l'initialisation de la base
.nvmrc Version de Node.js (22), lue par la CI
.gitleaks.toml Règles de détection de secrets et valeurs publiques autorisées
.editorconfig, .gitattributes Indentation et fins de ligne communes
LICENSE Licence MIT du code de BlockLucky, avec une note sur les licences des dépendances (BUSL-1.1 de @chainlink/contracts)
SECURITY.md Politique de signalement des vulnérabilités
CONTRIBUTING.md Règles de contribution
.vscode/launch.json Configurations de débogage de l'éditeur

Intégration continue

Fichier Rôle
.github/workflows/ci.yml Contrôles par projet, intégration sur la chaîne, images Docker, gitleaks
.github/workflows/codeql.yml Analyse CodeQL hebdomadaire et à chaque pull request
.github/dependabot.yml Mises à jour hebdomadaires des dépendances npm, Docker et Actions
.github/CODEOWNERS Relecteurs obligatoires par dossier
.github/pull_request_template.md Modèle de description des pull requests
.github/scripts/check-static-links.mjs Vérification des ressources locales du site de l'Office de Tourisme

Smart contracts

Fichier Rôle
contracts/BlockLucky.sol Contrat de loterie : tours, tickets, tirage VRF, cagnotte, remboursements, commission, pause, rôles
contracts/BlockLuckyPOAP.sol Badge ERC-721 non transférable, un par participant et par tour
hardhat.config.ts Compilateur 0.8.34, réseaux localhost et sepolia, clé Etherscan
scripts/deploy-local.ts Déploiement local avec coordinateur VRF simulé et rôles séparés (administrateur n° 2, trésorerie n° 1, opérateur du backend)
scripts/local-vrf-responder.ts Oracle VRF simulé qui répond aux demandes d'aléa
scripts/deploy-sepolia.ts Déploiement Sepolia avec contrôles du coordinateur et de l'abonnement, attribution des rôles au multisig, à la trésorerie et à l'opérateur, renonciation du déployeur
scripts/setup-vrf-sepolia.ts Création et financement en ETH de l'abonnement Chainlink VRF (npm run vrf:sepolia)
scripts/register-automation-sepolia.ts Inscription de l'upkeep Chainlink Automation (npm run automation:sepolia)
scripts/verify-sepolia.ts Publication du code source sur Etherscan (npm run verify:sepolia)
scripts/lib/roles.ts Plan, attribution et contrôle des rôles des deux contrats
scripts/lib/sepolia.ts Adresses Chainlink de Sepolia, ABI minimales, fichier deployments/sepolia-vrf.json
scripts/lib/deployment.ts Configuration des tours par variables d'environnement (un ticket par participant par défaut), écriture de deployments/
scripts/export-abi.mjs Copie des ABI vers le backend, mode --check pour la CI
docker/start-local-chain.sh Démarrage du conteneur : nœud, déploiement, oracle
test/BlockLucky.test.ts Tests unitaires du contrat de loterie
test/BlockLucky.t.sol Tests de fuzzing en Solidity
test/BlockLuckyPOAP.test.ts Tests du badge
test/roles.test.ts Tests de la répartition des rôles par les scripts
scripts/check-coverage.mjs Exigence de 100 % de couverture des lignes
slither.config.json Configuration de l'analyse statique Slither

Voir Smart contracts.

Backend

Démarrage et configuration

Fichier Rôle
src/server.ts Point d'entrée de l'API : serveur HTTP, Socket.IO, workers si RUN_WORKERS, arrêt propre
src/worker.ts Point d'entrée du worker : files, indexeur, keeper, sonde sur PORT + 1
src/app.ts Application Express : middlewares globaux, CORS, maintenance, rate limiting, montage des routes sous /api/v1 et /api
src/config/env.config.ts Schéma Zod de toutes les variables d'environnement et contrôles de production
src/config/prisma.config.ts Client Prisma, pool et délais PostgreSQL
src/config/redis.config.ts Client Redis avec préfixe, délais et repli en mémoire
prisma/schema.prisma Modèle de données
prisma/seed.ts Données de démonstration
.env.example Valeurs de développement de chaque variable
Dockerfile Image multi-étapes, cibles migrator et runtime

Blockchain

Fichier Rôle
src/blockchain/chain.client.ts Fournisseurs RPC, compte opérateur, instances des contrats
src/blockchain/lottery.gateway.ts Lecture des tours, achats, tirage, retrait, traduction des erreurs du contrat
src/blockchain/lottery.indexer.ts Projection des événements du contrat dans PostgreSQL
src/blockchain/lottery.keeper.ts Keeper du tirage et démarrage des services blockchain
src/blockchain/draw-reveal.ts Heure à laquelle le tour est devenu tirable et heure de révélation, gardées dans Redis
src/blockchain/chain-actions.ts File des actions on-chain (cagnotte, remboursement, badge)
src/blockchain/wallet.service.ts Création, chiffrement et dotation des portefeuilles intégrés
src/blockchain/poap.metadata.ts Métadonnées et visuel des badges
src/blockchain/abi/BlockLucky.json ABI du contrat, générée

Transverse

Fichier Rôle
src/middlewares/auth.middleware.ts Vérification du JWT
src/middlewares/rbac.middleware.ts Contrôle des rôles en base et 2FA des administrateurs
src/middlewares/age-verification.middleware.ts Refus 403 AGE_VERIFICATION_REQUIRED tant que l'âge du compte n'est pas vérifié
src/middlewares/body-parser.middleware.ts Analyse des corps JSON : 1 Mo par défaut, 12 Mo pour l'envoi de la pièce d'identité, corps brut des webhooks
src/middlewares/idempotency.middleware.ts En-tête Idempotency-Key
src/middlewares/rateLimiter.middleware.ts Limites de débit partagées dans Redis
src/middlewares/error.middleware.ts Format unique des erreurs
src/services/session.service.ts Émission et révocation des sessions
src/services/oauth-verifier.service.ts Vérification des jetons d'identité Google
src/services/otp-challenge.service.ts Codes email à usage unique, verrouillage après échecs, tickets de connexion (loginTicket) de la 2FA par application
src/services/otp-challenge.service.ts Codes à 6 chiffres de connexion, d'inscription et de réinitialisation, verrouillage après échecs
src/services/ledger.service.ts Mouvements d'EtherPoints
src/utils/crypto.util.ts Chiffrement AES-256-GCM des textes et des images, hachage bcrypt, HMAC, comparaison à temps constant
src/utils/identity-image.util.ts Décodage et contrôle des images d'identité (JPEG ou PNG, 4 Mo au plus)
src/observability/metrics.ts Métriques Prometheus
src/observability/shutdown.ts Arrêt propre
src/api/system/system.routes.ts Sondes de santé et configuration des clients
src/socket/socket.handler.ts Serveur Socket.IO
src/socket/event-bridge.ts Relais des événements du worker vers les clients
src/queues/queue.options.ts Tentatives et rétention des jobs

Modules métier

Chaque dossier de src/api/ suit le même découpage : *.routes.ts (routes et validation), *.controllers.ts (HTTP), *.services.ts (règles métier), *.repo.ts (Prisma), *.validators.ts (schémas Zod). Le plus central est lottery.services.ts. Voir Modules métier.

Tests

Fichier Rôle
__tests__/setup-env.ts Environnement commun des tests
__tests__/chain/onchain-lottery.chain.ts Scénarios sur une vraie chaîne (npm run test:chain)
jest.chain.config.json Configuration Jest de ces scénarios
scripts/check-env-example.mjs Cohérence entre .env.example et le schéma

Frontend web

Fichier Rôle
next.config.mjs En-têtes de sécurité, CSP calculée depuis les URL de l'API, sortie standalone
src/app/layout.tsx Mise en page racine
src/app/globals.css Jetons de couleur repris du mobile, rayons, échelle typographique, thèmes clair et sombre
src/app/fonts/ Police Inter chargée par next/font/local, avec sa licence
src/components/ui/Icon.tsx, src/components/ui/iconData.ts Icônes SVG copiées du mobile
src/components/layout/AppShell.tsx Barre latérale, en-tête et barre d'onglets des espaces connectés
src/app/providers.tsx Store Redux, restauration de la session, thème, capture de la source UTM, fenêtres globales, bandeau de consentement
src/content/legal.ts Textes des conditions générales, du règlement, des mentions légales, de la confidentialité, des traceurs et de la charte de transparence, en français et en anglais (même fichier sur le mobile)
src/lib/consent.ts, src/components/layout/ConsentBanner.tsx Choix de mesure d'audience (bl.consent.choice, 6 mois) et bandeau de consentement
src/hooks/useSound.ts Sons de la roue et du chronomètre, préférence bl.pref.sound
src/lib/config.ts URL de l'API et constantes de la loterie
src/store/api/baseApi.ts Client RTK Query, en-tête d'authentification
src/store/index.ts Store Redux
src/hooks/useBlockLuckyWallet.ts Portefeuille intégré et achat de tickets
src/hooks/useAgeVerification.ts Statut de vérification d'âge relu par GET /user/identity et recopié dans le profil stocké
src/hooks/useSocket.ts, src/lib/socket.ts Temps réel
src/components/layout/GlobalOverlays.tsx Fenêtres globales : points gagnés, relance, file d'attente, informations réseau
src/theme/ThemeProvider.tsx Thème clair ou sombre et traductions
src/app/mairie/page.tsx Tableau de bord de la Mairie
src/app/mairie/identites/page.tsx Examen des pièces d'identité et décision sur la vérification d'âge
src/app/mairie/comptes/page.tsx Comptes Mairie et partenaires : création avec invitation, changement et retrait de rôle
src/app/(citoyen)/billetterie/page.tsx Achat et cadeau de tickets
src/app/(citoyen)/tirage/page.tsx Salle de tirage en direct
Dockerfile Image de production

Voir Frontend web.

Application mobile

Fichier Rôle
src/App.tsx Point d'entrée
app.json Configuration Expo
eas.json Profils de build EAS (development, preview, production)
src/navigation/RootNavigator.tsx Navigation racine, bascule authentifié ou non, écrans empilés, ouverture de la vérification d'âge
src/navigation/MainTabs.tsx Quatre onglets : Accueil, Mes tickets, Parrains, Profil
src/types/navigation.types.ts, src/navigation/hooks.ts Paramètres typés des routes et hooks de navigation
src/services/api.client.ts Client HTTP et URL de l'API
src/services/socket.client.ts Client Socket.IO
src/services/secureStorage.ts Stockage sécurisé du jeton de session
src/store/api/baseApi.ts Client RTK Query
src/hooks/useAuth.ts Connexion par mot de passe ou Google, inscription, vérification des codes avec loginTicket, réinitialisation, déconnexion
src/hooks/useSound.ts Sons de la roue et du chronomètre (expo-audio), préférence blocklucky_sound_enabled
src/screens/settings/LegalScreen.tsx, src/content/legal.ts Écran Legal et textes légaux partagés avec le web
src/hooks/useCitizenWallet.ts Portefeuille intégré, achat et cadeau, classement des erreurs
src/screens/settings/VerifyAgeScreen.tsx Envoi du recto et du verso de la pièce d'identité
src/theme/ThemeProvider.tsx, src/theme/colors.ts Thème et jetons de couleur de la maquette
src/components/ui/icons/Icon.tsx Icônes SVG du design system

Voir Application mobile.

Office de Tourisme

Fichier Rôle
assets/js/main.js Point d'entrée JavaScript commun
assets/js/data/site.js Identité et coordonnées de l'Office, lien vers l'application de loterie (lotteryAppUrl), menus
assets/js/data/places.js, events.js, content.js Contenus : lieux, événements, articles
assets/js/modules/cart.js Panier de la billetterie
assets/js/modules/cookies.js Bandeau de consentement
assets/css/tokens.css Variables de la charte graphique
docker/nginx.conf Configuration nginx
docker/security-headers.conf En-têtes de sécurité et CSP
serve.json En-têtes du serveur de développement

Voir Office de Tourisme.

Tests de charge

Fichier Rôle
load-tests/smoke.js Test de fumée
load-tests/load.js Profils de charge, stress, pic et endurance

Voir Tests de charge.

Documentation officielle

Fichier Rôle
content/SUMMARY.md Liste et ordre des pages
scripts/build.mjs Construction du site statique
scripts/lib/generators.mjs Tableaux générés depuis le code
content/_data/ Descriptions des tableaux générés

Voir Écrire la documentation.