Objectif de cette documentation : un développeur senior qui découvre GoLivra doit pouvoir comprendre l'intégralité du projet et commencer à contribuer sans poser aucune question.
Cette documentation est le manuel technique complet de GoLivra. Elle couvre l'architecture, les conventions de développement, la sécurité, les paiements, la base de données, les déploiements, les décisions techniques et les procédures d'exploitation.
Si vous n'avez que 5 minutes, lisez ceci puis allez au guide de démarrage rapide.
GoLivra est une marketplace de livraison et commerce local à Brazzaville (Congo). Elle connecte 6 acteurs (clients, restaurateurs, commerçants, livreurs, administrateurs, entreprises logistiques) via 4 applications :
| Application | Dossier | Rôle | Stack |
|---|---|---|---|
| Mobile | golivra/ |
App clients + vendeurs + livreurs | Expo 54 · React Native 0.81 · React 19 |
| Backend | golivra-backendcd/ |
API centrale (le cerveau) | Node 20+ · Express 5 · Supabase JS |
| Admin | golivra-admin/ |
Back-office admin + logistique | TanStack Start · Vite · Tailwind 4 · Radix |
| Vitrine | golivra-site-vitrine/ |
Site marketing public | TanStack Start · Vite · Tailwind |
Règle d'or : toute logique sensible (prix, statuts, rôles, OTP, sessions, argent) vit dans le backend. Les clients n'échangent que du JSON et ne connaissent jamais les secrets.
Choisissez votre point d'entrée selon ce que vous cherchez.
| Document | Pour quoi faire |
|---|---|
| architecture/vision.md | Pourquoi GoLivra existe, quel problème elle résout |
| architecture/overview.md | Architecture globale + schémas |
| architecture/request-lifecycle.md | Cycle complet d'une requête HTTP |
| architecture/modules.md | Les 4 dépôts et leurs responsabilités |
| architecture/diagrams.md | Tous les diagrammes (flux, déploiement, rôles…) |
| Document | Pour quoi faire |
|---|---|
| backend/structure.md | Organisation du code (controllers/services/routes…) |
| backend/request-cycle.md | Comment circule une requête dans Express |
| backend/controllers-vs-services.md | Pourquoi Controller ≠ Service |
| backend/authentication.md | Sessions opaques, OTP, login, logout |
| backend/authorization.md | Les 6 rôles et qui peut appeler quoi |
| backend/error-handling.md | Codes d'erreur normalisés |
| backend/observability.md | Incidents, alerting, santé endpoints |
| Document | Pour quoi faire |
|---|---|
| payments/overview.md | Vue d'ensemble du module paiements |
| payments/escrow-flow.md | Cycle escrow (hold → release → refund) |
| payments/pawapay.md | Intégration PawaPay Mobile Money |
| payments/webhooks.md | Webhooks signés HMAC |
| payments/withdrawals.md | Retraits marchands / livreurs |
| payments/commissions.md | Moteur de commission |
| payments/errors.md | Échecs, retries, réconciliation |
| Document | Pour quoi faire |
|---|---|
| database/overview.md | Vue d'ensemble + conventions de nommage |
| database/schema-diagram.md | Diagramme des 42 tables et relations |
| database/tables.md | Dictionnaire détaillé table par table |
| database/enums.md | Types énumérés (statuts, rôles…) |
| database/triggers.md | Fonctions et triggers automatiques |
| database/migrations.md | Gestion du schéma (amendments) |
| Document | Pour quoi faire |
|---|---|
| api/overview.md | Conventions (auth, codes, pagination) |
| api/authentication.md | Endpoints auth + OTP |
| api/catalog.md | Endpoints entreprises, produits, catégories |
| api/orders.md | Endpoints commandes + panier |
| api/payments.md | Endpoints paiement + portefeuille |
| api/delivery.md | Endpoints livraison + logistique |
| api/admin.md | Endpoints admin |
| api/account.md | Adresses, favoris, avis, notifications |
| Document | Pour quoi faire |
|---|---|
| security/authentication-model.md | Pourquoi sessions opaques (pas JWT) |
| security/trust-boundaries.md | Zones de confiance |
| security/secrets.md | Gestion des secrets et clés |
| security/payments-security.md | Sécurité financière (idempotence, HMAC) |
| security/checklist.md | Checklist de revue sécurité |
| Document | Pour quoi faire |
|---|---|
| mobile/structure.md | Organisation du code (app/components/lib…) |
| mobile/routing.md | Expo Router, espaces (tabs/vendor/courier) |
| mobile/state-management.md | Zustand, Contexts, TanStack Query |
| mobile/secure-storage.md | SecureStore, biométrie |
| mobile/adding-a-screen.md | Comment ajouter un écran pas à pas |
| mobile/build.md | Build EAS, Play Store, App Store |
| Document | Pour quoi faire |
|---|---|
| admin/structure.md | Organisation du code |
| admin/routing.md | TanStack Router, espaces admin/entreprise |
| admin/components.md | Composants shadcn/Radix |
| Document | Pour quoi faire |
|---|---|
| deployment/overview.md | Environnements (dev / préprod / prod) |
| deployment/backend.md | Déployer le backend sur Render |
| deployment/admin.md | Déployer l'admin (static site) |
| deployment/mobile.md | Build mobile EAS + stores |
| deployment/environment.md | Toutes les variables d'environnement |
| Document | Pour quoi faire |
|---|---|
| coding/style.md | Comment coder dans GoLivra (les « Toujours / Jamais ») |
| coding/git.md | Branches, commits, sous-modules |
| coding/review-checklist.md | Checklist de revue de PR |
| Document | Pour quoi faire |
|---|---|
| guides/quickstart.md | Démarrer le projet en local |
| guides/new-developer.md | Onboarding nouveau développeur |
| guides/add-feature.md | Ajouter une fonctionnalité de bout en bout |
| decisions/README.md | ADR — Architecture Decision Records |
- Tous les chemins sont relatifs à la racine du workspace (
M:\Go Livra App\) sauf indication contraire. - Références code :
dossier/fichier.ext:ligne— cliquables dans la plupart des éditeurs. - Les exemples de code reflètent le code réel de GoLivra, pas du pseudocode générique.
- Devise : toutes les sommes sont en FCFA (XAF).
- Diagrammes : Mermaid (rendus nativement par GitHub, GitLab, VS Code).
Cette documentation doit suivre le code. Règles :
- Toute PR qui modifie l'architecture, l'API, le schéma DB ou la sécurité doit mettre à jour la doc correspondante.
- Une fonctionnalité non documentée est considérée comme inexistante.
- Les ADR (
docs/decisions/) sont immuables : on n'édite pas une décision passée, on en écrit une nouvelle qui la supplante.
Dernière mise à jour de cette index : juin 2026 · Schéma DB documenté : v3.0 (42 tables) · Backend : Express 5 · Mobile : Expo 54