Spec fonctionnelle (lien)

Ce site (dev-docs) documente le code. Il existe un second site, complémentaire, qui documente le métier : la spécification fonctionnelle.

Où la trouver

Code source : doc/site (à la racine payment_gateway/, à côté de app/).
Stack : Next.js 16 + MDX (différent de ce site-ci, qui est en Astro Starlight).
Contenu source : doc/site/content/**/*.mdx.

Pour la lancer en local : cd doc/site && npm install && npm run dev.

Qui répond à quoi

Question	Site
Quoi ? Pourquoi ? (règles métier, contrats)	Spec fonctionnelle (`doc/site`)
Comment ? (implémentation, fichiers, appels)	Ce site (`dev-docs`)

Inventaire du contenu de la spec

La spec couvre (fichiers doc/site/content/) :

Fondations & moteur

vision.mdx — périmètre : ce que E-Pay fait et ne fait pas
domain-model.mdx — entités PaymentSession, PaymentLeg → voir aussi Modèle de domaine
state-machines.mdx — cycles de vie → voir aussi Machines à états
orchestration.mdx — séquencement, outbox, rollback → voir aussi Outbox & orchestration
providers.mdx, psp-registry.mdx — interface PaymentProvider + registre → voir aussi Contrats
refunds.mdx — stratégies de remboursement
security.mdx — PCI-DSS, DSP2, credentials → voir aussi Sécurité

Référence API (content/api/)

sessions.mdx, legs.mdx, merchants.mdx, webhooks.mdx, bootstrap.mdx

Intégration & produit

sdk.mdx, bootstrap-architecture.mdx, plugins.mdx
content/product/ : overview.mdx, buyer-journey.mdx, merchant.mdx, white-label.mdx
glossary.mdx

Documents de référence dans le dépôt `app/`

Au-delà des deux sites, plusieurs documents .md font autorité sur des points précis :

Document	Sujet
`ECOSYSTEM.md`	Inventaire des briques, contrat d’API publique, sécurité multi-tenant
`ARCHITECTURE.md`	Hexagonal, ports/adapters, outbox, erreurs
`STACK.md`	Technos retenues / rejetées → Stack
`CONVENTIONS.md`	Style de code → Conventions
`ecosystem/CONTRACTS.md`	Interfaces partagées → Contrats
`DISCOVERY.md`	Audit pré-implémentation, décisions ouvertes
`E2E-ADYEN.md`	Runbook d’intégration Adyen de bout en bout
`SHOPIFY-INTEGRATION.md`	Approches d’intégration Shopify