Service Orchestrator

Point d'entrée central de la plateforme Nex. Orchestre les workflows multi-services (création d'organization, transferts, onboarding KYC) et garantit la cohérence des opérations métier en gérant les sagas et les compensations.

Attribut	Valeur
Package	@nex/service-orchestrator
Port	3004
Schéma DB	dédié (PostgreSQL)
Swagger	actif
Owner	@platform-team

Pourquoi ce service existe

• Centraliser les workflows métier qui touchent plusieurs microservices.
• Garantir la cohérence : un workflow réussit ou compense, jamais d'état partiel persisté côté client.
• Cacher la complexité : les clients (mobile, web) ne voient qu'une API simple.
• Appliquer la règle d'or : les services métier (Customer, Ledger, Notification) ne sont jamais appelés directement par les clients.

Architecture cible

Exposition publique vs interne

Service	Exposition	Accès
API Gateway	Publique	Clients (mobile, web)
Auth Service	Publique (via Gateway)	Login, register, refresh token
Orchestrator Service	Publique (via Gateway)	Workflows métier
Configuration Service	Publique (via Gateway)	Lecture params, fees
Customer Profiles KYC	Interne uniquement	Via Orchestrator
Ledger Wallets	Interne uniquement	Via Orchestrator
Notification Service	Interne uniquement	Via Orchestrator

Communication inter-services

Client → API Gateway → Orchestrator → Services Métier
                                   ↓
                            HTTP synchrone
                            Headers propagés (X-User-Id, X-Request-Id)

Plan de la documentation

La référence complète du service est éclatée en trois pages thématiques.

Page	Contenu
Architecture interne	Structure du service (Clean Architecture, modules, controllers), interfaces des services externes, configuration réseau.
Workflows et bonnes pratiques	Exemple complet (création d'organization), workflows à implémenter, patterns saga / compensation.
Migration et refactoring	Structure actuelle vs cible, analyse détaillée, plan de refactoring, checklist de conformité, FAQ.