Bienvenue & parcours de lecture

Cette documentation existe pour une raison simple : permettre à quelqu’un qui ne connaît pas le code de comprendre tout Titreo E-Pay, puis de le reprendre ou de le passer à d’autres développeurs.

Elle est volontairement progressive : du général (à quoi sert le système) vers le détaillé (à quoi sert chaque fichier et quel chemin prennent les appels).

Qu’est-ce que Titreo E-Pay, en une phrase

Un orchestrateur de paiement multi-instruments : il combine, dans une seule session de paiement, une ou plusieurs cartes cadeaux (Titreo et autres émetteurs) avec un moyen de paiement classique (PSP : Stripe, Adyen…), avec rollback automatique si une étape échoue.

Nom interne

Le projet s’appelle Titreo E-Pay côté produit, et OrchPay en interne. Les deux désignent la même chose.

Le modèle mental à retenir

Trois idées suffisent pour tout comprendre :

1. Une session de paiement (PaymentSession) contient des « jambes » (PaymentLeg). Chaque jambe est un moyen de paiement : une carte cadeau, ou un PSP. Le total des jambes doit couvrir le montant.
2. Le paiement est asynchrone et fiable grâce à un outbox. Quand on déclenche un paiement, le système n’appelle pas Stripe « en direct » dans la requête HTTP. Il inscrit une tâche dans une table outbox, et un worker la traite en arrière-plan (débit gift → autorisation PSP → capture), avec retry et compensation en cas d’échec.
3. Le code est hexagonal. Le métier (domaine) ne connaît ni Fastify, ni Firebird, ni Stripe. Tout passe par des ports (interfaces) implémentés par des adapters. C’est ce qui rend chaque PSP ou émetteur de carte interchangeable.

Si vous gardez ces trois idées en tête, le reste n’est que du détail.

Parcours de lecture conseillé

Lisez dans cet ordre. Chaque section suppose la précédente comprise.

flowchart TD
  A["1. Vue d'ensemble de l'écosystème"] --> B["2. Concepts transverses"]
  B --> C["3. Backend api/ en profondeur"]
  C --> D["4. SDK & checkout & adapters"]
  D --> E["5. Plugins, consoles, démos"]
  E --> F["6. Annexes : env, ports, maturité"]

1. Vue d’ensemble de l’écosystème — la carte de toutes les briques et comment elles se parlent. Indispensable avant tout.
2. Concepts transverses — hexagonal, domaine, machines à états, outbox, idempotence, sécurité, contrats. Le pourquoi avant le où.
3. Backend api/ — le cœur, couche par couche, fichier par fichier, avec des parcours d’appel tracés de la requête jusqu’à la base.
4. SDK & checkout — comment les clients (JS, PHP, navigateur) consomment l’API.
5. Plugins & consoles — les intégrations e-commerce et back-offices.
6. Annexes — variables d’environnement, ports, conventions, maturité.

Comment cette doc se distingue de la spec fonctionnelle

Il existe deux sites de documentation, complémentaires :

Site	Répond à	Contenu
Spec fonctionnelle (doc/site)	Quoi ? Pourquoi ?	Modèle de domaine, machines à états, contrats d’API, règles métier
Ce site (dev-docs)	Comment ?	Implémentation réelle : dossiers, fichiers, fonctions, chemins d’appel

Quand un détail métier est ambigu, la spec fonctionnelle fait foi. Ce site décrit ce que le code fait réellement aujourd’hui — y compris ses zones encore en chantier, signalées explicitement.

Badges de maturité

Chaque brique porte un état : actif, prototype, squelette ou POC. Ne supposez jamais qu’un dossier qui « existe » est terminé — vérifiez son badge sur sa page et dans le tableau de maturité.

Conventions de cette documentation

• Les chemins de fichiers sont en code et toujours relatifs à app/ (ex. api/src/domain/session/session.ts).
• Les encadrés signalent les pièges, invariants et contraintes externes.
• Les diagrammes sont en Mermaid (machines à états, séquences, flux).
• On ne duplique pas la source de vérité : on renvoie vers les fichiers .md du dépôt (ARCHITECTURE.md, CONVENTIONS.md, ecosystem/CONTRACTS.md, …) et vers la spec fonctionnelle.