ADR-0015 — Architecture transaction-flow config-driven

Status : Accepted Date : 2026-04 (NEX-438) Deciders : équipe Nex (ticket NEX-438) Tickets : NEX-438

Contexte

Nex porte 7 flows transactionnels distincts : P2P, MERCHANT_PAY, CASH_IN, CASH_OUT, MA_CASH_OUT, MA_COMM_COLLECT, MASTER_AGENT_CASH_IN. Chaque flow a sa séquence d’étapes (saisie, sélection, recap, confirmation, etc.).

Approche initiale : un écran mobile hard-codé par flow. Limitations :

• Ajouter un flow = re-déployer l’app mobile (≥ semaines de cycle store Apple/Google).
• Modifier l’ordre d’étapes d’un flow existant = re-déploiement.
• Impossibilité de tester rapidement une variation A/B d’un flow.
• Drift entre les 3 apps mobiles qui implémentent chacune leur version.

Décision

1. Chaque flow est décrit par un FlowSchema stocké côté configuration service : une liste ordonnée d’étapes typées (amount_input, recipient_select, risk_evaluation, recap, pin_confirm, …).
2. Le FlowSchema est livré au client dans intent.flow_snapshot au moment du POST /v1/intents, ce qui le gel sur la durée de vie de l’intent (anti-drift).
3. Le client mobile rend dynamiquement chaque étape selon son type via des renderers @nex/ui-mobile.
4. Les flows sont versionnés côté configuration ; on peut déployer un nouveau schéma sans toucher au client.
5. Sandbox CMMS : un simulateur permet de rejouer n’importe quel FlowSchema actif avec impersonation, pour valider une modif de schéma avant rollout (/sandbox/flow).

Conséquences

Positives

• Déploiement d’un nouveau flow ou d’une variation sans toucher l’app mobile.
• Un seul moteur de rendu (@nex/ui-mobile step renderers) partagé entre les 3 apps.
• A/B testing natif sur les flows.
• Onboarding nouveau dev mobile : il comprend le rendu, pas la logique métier de chaque flow.
• Compliance / audit : un auditeur lit le FlowSchema JSON pour comprendre ce qu’un utilisateur a vu.

Négatives / risques

• Schéma cassé en prod = tous les utilisateurs bloqués sur ce flow. Mitigation : flow_snapshot figé par intent + validation stricte au create + sandbox CMMS obligatoire avant rollout.
• Complexité de l’éditeur de schémas côté CMMS (Lot d’engineering UX dédié).
• Rétro-compatibilité des flow_snapshot figés : un dev peut modifier un step renderer et casser un intent ancien. Mitigation : versionner les step types.

Alternatives écartées

• Garder du code hard-codé par flow — bloqué par cycle store.
• Server-driven UI complet (rendu HTML pushé) — incompatible avec UX native mobile.
• Webviews dans les apps — UX dégradée, latence.

Suivi

• Voir /architecture/transaction-flows-config-driven pour le DSL.
• Voir /architecture/sandbox-flow-simulator pour le simulateur CMMS.
• Voir ADR-0006 (intent canonique) qui structure la frontière.
• Voir ADR-0007 (prefetched policy trust boundary) qui sécurise l’étape risk_evaluation.