Vue d'ensemble de l'écosystème

Titreo E-Pay n’est pas une application monolithique : c’est un écosystème de briques indépendantes. Cette page est la carte. Gardez-la sous la main en lisant le reste.

Principe fondateur : découplage par contrat

Chaque brique est (à terme) un dépôt GitLab indépendant, déployable seul. Elles ne se parlent que par trois canaux stables et versionnés :

• le contrat HTTP /v1/* (décrit par openapi.json) ;
• des webhooks signés HMAC (API → marchand, et PSP → API) ;
• un manifest signé Ed25519 (API → loader navigateur).

Règle d’or

Ajouter un PSP, un émetteur de carte cadeau ou un plugin CMS ne doit jamais modifier le cœur de l’API. Le cœur opère sur des contrats abstraits (voir Contrats inter-briques) ; on substitue Stripe → Adyen en changeant d’adapter, sans toucher au cœur.

Modèle financier

Aucun fonds ne transite par Titreo E-Pay. Chaque marchand encaisse directement sur ses propres comptes PSP et ses contrats émetteurs. Titreo est une couche d’orchestration technique pure — ce qui simplifie énormément la conformité (pas d’agrément d’établissement de paiement requis pour le rôle d’orchestrateur).

Le flux type, vu de haut

sequenceDiagram
  participant M as Boutique marchand
  participant API as API Titreo E-Pay
  participant B as Navigateur client
  participant PSP as PSP (Stripe/Adyen)
  participant G as Émetteur gift (Titreo)

  M->>API: POST /v1/sessions (montant panier)
  M->>B: redirige vers la page de checkout
  B->>API: GET /v1/sessions/:id/bootstrap (manifest signé)
  B->>B: charge les adapters clients signés
  B->>API: ajoute leg(s) gift + leg PSP, puis submit
  API->>G: débit carte cadeau
  API->>PSP: autorisation puis capture
  API-->>M: webhook signé (session.completed)
  Note over API,G: rollback gift si le PSP échoue

Carte des briques

flowchart TB
  subgraph coeur["Brique centrale"]
    API["api/ — backend Fastify + Firebird<br/>domaine, orchestration, webhooks, registry"]
  end

  subgraph sdk["SDK & clients HTTP"]
    SDKJS["sdk-js"]
    SDKPHP["sdk-php"]
  end

  subgraph nav["Couche navigateur (checkout)"]
    CKSDK["checkout-sdk (Lit)"]
    CKPAGE["checkout-page (Next.js)"]
    ADStripe["adapter-stripe-client"]
    ADAdyen["adapter-adyen-client"]
    ADGift["adapter-titreo-gift-client"]
  end

  subgraph plugins["Plugins e-commerce"]
    PRESTA["plugin-prestashop"]
    SHOP["epay-shopify-app"]
  end

  subgraph consoles["Consoles & démos"]
    CADMIN["console-admin"]
    CMERCH["console-merchant"]
    DEMO["demo-shop"]
  end

  SDKJS --> API
  SDKPHP --> API
  CKPAGE --> CKSDK
  CKSDK --> SDKJS
  CKSDK -.charge.-> ADStripe
  CKSDK -.charge.-> ADAdyen
  CKSDK -.charge.-> ADGift
  PRESTA --> SDKPHP
  SHOP --> API
  CADMIN --> API
  CMERCH --> API
  DEMO --> SDKJS

Inventaire & rôles

Brique	Rôle	Stack	Maturité
api/	Le cœur : domaine, orchestration, outbox, webhooks, registry PSP/gift, sécurité multi-tenant	Node 22, TS strict, Fastify 5, Zod, Firebird 5	actif
sdk-js	Client HTTP typé (ESM+CJS) pour l’API /v1/*	TS, tsup, fetch	actif
sdk-php	Client HTTP PHP (PSR-18) pour les plugins CMS	PHP 8.2, PSR-7/17/18	actif
checkout-sdk	Composants Web (Lit) du checkout + chargeur d’adapters signés	Lit 3, esbuild	actif
adapter-stripe-client	Adapter PSP navigateur : monte Stripe Elements, tokenize, 3DS	TS, @stripe/stripe-js	actif
adapter-adyen-client	Adapter PSP navigateur : monte Adyen Web Components	TS, @adyen/adyen-web	actif
adapter-titreo-gift-client	Adapter gift navigateur : lookup de solde	TS	prototype
checkout-page	Page de checkout hébergée qui monte le checkout-sdk	Next.js 15	actif
epay-shopify-app	App Shopify : admin + extensions checkout + miroir gift card	React Router 7, Prisma	actif (dev)
plugin-prestashop	Module de paiement PrestaShop 8	PHP, PrestaShop PaymentModule	prototype
demo-shop-prestashop	Sandbox Docker PrestaShop pour tester le plugin	Docker, MariaDB	sandbox
console-admin	Back-office interne Titreo (gestion marchands)	Next.js 15	squelette
console-merchant	Console self-service marchand	Next.js 15	squelette
demo-shop	Storefront de démonstration	Next.js 15	prototype
giftcard-feasibility	POC de faisabilité du miroir gift card sur Shopify	TS, Shopify API	POC

État réel ≠ schéma cible

Le fichier ECOSYSTEM.md du dépôt décrit l’organisation cible (un repo GitLab par brique). En pratique, tout vit aujourd’hui dans un seul dossier app/, et plusieurs briques sont des squelettes. Voir le tableau de maturité pour l’état exact de chacune.

Où aller ensuite

• Comprendre pourquoi c’est organisé ainsi → Architecture hexagonale
• Comprendre le cœur → Backend api/
• Le détail des contrats entre briques → Contrats inter-briques

Source de vérité complémentaire dans le dépôt : ECOSYSTEM.md (inventaire cible, CI/CD inter-repos), et ecosystem/CONTRACTS.md (interfaces partagées).