Aller au contenu principal

Architecture Laravel

Statut​

Document de cadrage backend — version initiale.

Vue d'ensemble​

Le backend cible de DMV est une API Laravel centrale modulaire. Il doit porter la logique métier commune de l'écosystème : DMV public, backoffice, PlayLoop, AssoSuite, Mairie et futures applications connectées.

Le dossier api contient une application Laravel avec PHP ^8.3, Laravel ^13.0, Sanctum, Stripe PHP et Firebase JWT.

Rôle du backend​

Le backend doit :

  • exposer une API versionnée sous /api/v1 ;
  • centraliser les règles métier ;
  • gérer authentification, autorisation et RBAC ;
  • protéger les mutations ;
  • orchestrer les services partagés ;
  • déclencher jobs et traitements asynchrones ;
  • préparer la future AI Gateway ;
  • éviter la dispersion de logique métier dans les frontends.

État actuel visible​

ÉlémentÉtat visible
FrameworkLaravel ^13.0, PHP ^8.3.
APIRoutes sous /api/v1, health-check /api/v1/health.
AuthSanctum et validation JWT Supabase via firebase/php-jwt.
ModulesDomaines métier sous api/app/Modules.
ProvidersModules déclarés dans api/bootstrap/providers.php.
Middlewareidentify.app, ensure.admin, device.token, asso.access, mairie.access.
JobsExpireBoosts, ExpireAlertes, ProcessStripeWebhook visibles.
TestsTests feature par modules dans api/tests/Feature.

Modules métier visibles​

  • Identity
  • Territory
  • Actor
  • Publication
  • Community
  • Monetization
  • Settings
  • Analytics
  • PlayLoop
  • AssoSuite
  • Chat
  • Mairie
  • Admin

Principes d'architecture​

  • Un module correspond à un domaine métier identifiable.
  • Les contrôleurs restent fins.
  • La logique métier est portée par les services, policies, jobs ou objets dédiés.
  • Les Form Requests portent la validation d'entrée.
  • Les DTOs structurent les sorties quand ils existent.
  • Les décisions sensibles doivent rester côté backend.
  • Les frontends consomment l'API, sans répliquer les règles métier.

Vision cible​

La cible est une API Laravel centrale, modulaire et stable, avec :

  • contrats API documentés ;
  • services métier cohérents ;
  • actions ou cas d'usage explicites pour les opérations complexes ;
  • événements métier lorsque nécessaire ;
  • queues pour les traitements lourds ;
  • ressources ou DTOs harmonisés ;
  • observabilité et tests renforcés ;
  • AI Gateway centralisée pour les usages IA.

Points à clarifier​

  • Rôle exact de Supabase face à l'API Laravel.
  • Convention unique DTO vs API Resources.
  • Place future des Actions.
  • Stratégie d'événements métier.
  • Documentation exhaustive des endpoints.