You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

16 KiB

Raw Permalink Blame History

Diagrammes d'Architecture C4

Les diagrammes C4 (Context, Container, Component, Code) permettent de visualiser l'architecture à différents niveaux d'abstraction.

📋 Table des Matières

Niveau 1 : Diagramme de Contexte
Niveau 2 : Diagramme de Conteneurs
Niveau 3 : Diagramme de Composants (Reservation Service)
Diagramme de Séquence : Créer une Réservation
Diagramme d'Infrastructure

Niveau 1 : Diagramme de Contexte

Objectif : Vue d'ensemble du système et de son interaction avec les acteurs externes.

C4Context
    title Diagramme de Contexte - BricoLoc (Version Moderne)

    Person(client, "Client", "Particulier ou professionnel louant des outils")
    Person(admin, "Administrateur", "Gestionnaire de l'inventaire et des réservations")
    
    System(bricoloc, "BricoLoc Moderne", "Plateforme de location d'outils avec architecture microservices")
    
    System_Ext(stripe, "Stripe", "Service de paiement en ligne")
    System_Ext(email, "Service Email", "Envoi d'emails transactionnels (Resend/SendGrid)")
    System_Ext(storage, "Supabase Storage", "Stockage des images d'outils")
    
    Rel(client, bricoloc, "Recherche et loue des outils", "HTTPS")
    Rel(admin, bricoloc, "Gère inventaire et réservations", "HTTPS")
    
    Rel(bricoloc, stripe, "Traite les paiements", "API REST")
    Rel(bricoloc, email, "Envoie notifications", "API REST")
    Rel(bricoloc, storage, "Stocke/récupère images", "API REST")
    
    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Acteurs :

Client : Utilisateur final recherchant et louant des outils
Administrateur : Gestionnaire du système

Systèmes externes :

Stripe : Paiements sécurisés
Service Email : Notifications transactionnelles
Supabase Storage : Images des outils

Niveau 2 : Diagramme de Conteneurs

Objectif : Vue des principaux conteneurs (applications, services, bases de données).

C4Container
    title Diagramme de Conteneurs - BricoLoc Moderne

    Person(client, "Client", "Utilisateur du site")
    Person(admin, "Administrateur", "Gestionnaire système")

    Container_Boundary(bricoloc, "BricoLoc Moderne") {
        Container(webapp, "Application Web", "Next.js 14 (SSR/SSG)", "Interface utilisateur avec rendu serveur")
        Container(api_gateway, "API Gateway / BFF", "Next.js API Routes", "Orchestration des appels aux microservices")
        
        Container_Boundary(microservices, "Microservices") {
            Container(auth_svc, "Auth Service", "Supabase Auth", "Authentification et autorisation")
            Container(catalogue_svc, "Catalogue Service", "TypeScript", "Gestion des outils et catégories")
            Container(reservation_svc, "Reservation Service", "TypeScript", "Gestion des réservations")
            Container(inventory_svc, "Inventory Service", "TypeScript", "Gestion des stocks et disponibilité")
            Container(payment_svc, "Payment Service", "TypeScript", "Gestion des paiements")
            Container(notification_svc, "Notification Service", "TypeScript", "Envoi de notifications")
        }
        
        Container(event_bus, "Event Bus", "Supabase Realtime", "Communication asynchrone entre services")
        ContainerDb(database, "Base de Données", "PostgreSQL (Supabase)", "Données persistantes")
        Container(storage, "Storage", "Supabase Storage", "Fichiers et images")
    }

    System_Ext(stripe, "Stripe", "Paiements")
    System_Ext(email_provider, "Service Email", "Emails")

    ' Relations Client
    Rel(client, webapp, "Utilise", "HTTPS")
    Rel(admin, webapp, "Administre", "HTTPS")
    
    ' Relations WebApp
    Rel(webapp, api_gateway, "Appelle", "HTTP/API")
    
    ' Relations API Gateway vers Microservices
    Rel(api_gateway, auth_svc, "Authentifie", "API")
    Rel(api_gateway, catalogue_svc, "Liste outils", "API")
    Rel(api_gateway, reservation_svc, "Crée réservation", "API")
    Rel(api_gateway, inventory_svc, "Vérifie disponibilité", "API")
    Rel(api_gateway, payment_svc, "Traite paiement", "API")
    
    ' Relations Microservices vers Database
    Rel(catalogue_svc, database, "Lit/Écrit", "SQL")
    Rel(reservation_svc, database, "Lit/Écrit", "SQL")
    Rel(inventory_svc, database, "Lit/Écrit", "SQL")
    Rel(payment_svc, database, "Lit/Écrit", "SQL")
    
    ' Relations Event Bus
    Rel(reservation_svc, event_bus, "Publie events", "Realtime")
    Rel(inventory_svc, event_bus, "Écoute events", "Realtime")
    Rel(notification_svc, event_bus, "Écoute events", "Realtime")
    
    ' Relations externes
    Rel(payment_svc, stripe, "Traite paiements", "API REST")
    Rel(notification_svc, email_provider, "Envoie emails", "API REST")
    Rel(catalogue_svc, storage, "Stocke images", "API REST")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="2")

Conteneurs principaux :

Application Web : Next.js 14 (SSR/SSG)
API Gateway : Orchestration via Next.js API Routes
6 Microservices : Auth, Catalogue, Reservation, Inventory, Payment, Notification
Event Bus : Supabase Realtime (communication asynchrone)
PostgreSQL : Base de données principale
Storage : Fichiers et images

Niveau 3 : Diagramme de Composants (Reservation Service)

Objectif : Détail interne d'un microservice (exemple : Reservation Service).

C4Component
    title Diagramme de Composants - Reservation Service

    Container_Boundary(api_gateway, "API Gateway") {
        Component(api_routes, "API Routes", "Next.js", "Endpoints REST")
    }

    Container_Boundary(reservation_service, "Reservation Service") {
        Component_Boundary(application, "Application Layer") {
            Component(reservation_controller, "ReservationController", "TypeScript", "Gère les requêtes HTTP")
            Component(reservation_service_logic, "ReservationService", "TypeScript", "Logique métier et orchestration")
            Component(use_cases, "Use Cases", "TypeScript", "CreateReservation, CancelReservation, etc.")
        }
        
        Component_Boundary(domain, "Domain Layer") {
            Component(reservation_entity, "Reservation Entity", "TypeScript", "Entité métier")
            Component(reservation_factory, "ReservationFactory", "TypeScript", "Création d'entités")
            Component(reservation_repo_interface, "IReservationRepository", "Interface", "Contrat d'accès données")
            Component(business_rules, "Business Rules", "TypeScript", "Règles métier (validation, pricing)")
        }
        
        Component_Boundary(infrastructure, "Infrastructure Layer") {
            Component(supabase_repo, "SupabaseReservationRepository", "TypeScript", "Implémentation du repository")
            Component(event_publisher, "EventPublisher", "TypeScript", "Publication d'events")
        }
    }

    ContainerDb(database, "PostgreSQL", "Supabase", "Base de données")
    Container(event_bus, "Event Bus", "Supabase Realtime", "Communication async")
    Container(inventory_svc, "Inventory Service", "TypeScript", "Vérification disponibilité")

    ' Relations
    Rel(api_routes, reservation_controller, "Appelle", "HTTP")
    Rel(reservation_controller, reservation_service_logic, "Utilise", "DI")
    Rel(reservation_service_logic, use_cases, "Exécute", "")
    Rel(use_cases, reservation_factory, "Crée entités", "")
    Rel(use_cases, business_rules, "Applique règles", "")
    Rel(reservation_service_logic, reservation_repo_interface, "Utilise", "Interface")
    Rel(reservation_repo_interface, supabase_repo, "Implémenté par", "")
    Rel(supabase_repo, database, "Lit/Écrit", "SQL")
    Rel(reservation_service_logic, event_publisher, "Publie events", "")
    Rel(event_publisher, event_bus, "Envoie", "Realtime")
    Rel(reservation_service_logic, inventory_svc, "Vérifie dispo", "API")

    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="2")

Couches :

Application Layer : Controllers, Services, Use Cases
Domain Layer : Entités, Factories, Interfaces, Business Rules
Infrastructure Layer : Repositories, Event Publishers

Flux :

API Route → Controller
Controller → Service
Service → Use Case
Use Case → Factory/Rules → Repository
Repository → Database
Service → Event Publisher → Event Bus

Diagramme de Séquence : Créer une Réservation

Objectif : Flux complet de création d'une réservation (synchrone + asynchrone).

sequenceDiagram
    actor Client
    participant WebApp as Next.js WebApp
    participant API as API Gateway
    participant ResSvc as Reservation Service
    participant InvSvc as Inventory Service
    participant DB as PostgreSQL
    participant EventBus as Event Bus (Realtime)
    participant NotifSvc as Notification Service
    participant PaySvc as Payment Service

    Client->>WebApp: Remplit formulaire réservation
    WebApp->>API: POST /api/reservations
    
    API->>ResSvc: createReservation(data)
    
    Note over ResSvc: 1. Validation des données
    ResSvc->>ResSvc: validateReservationDates()
    
    Note over ResSvc: 2. Vérifier disponibilité
    ResSvc->>InvSvc: checkAvailability(outilId, dates)
    InvSvc->>DB: SELECT stock WHERE ...
    DB-->>InvSvc: Stock disponible
    InvSvc-->>ResSvc: { available: true }
    
    Note over ResSvc: 3. Calculer prix
    ResSvc->>ResSvc: calculatePrice(days, dailyRate)
    
    Note over ResSvc: 4. Créer réservation
    ResSvc->>DB: INSERT INTO reservations
    DB-->>ResSvc: reservation created
    
    Note over ResSvc: 5. Publier event (async)
    ResSvc->>EventBus: publish('reservation.created', data)
    
    ResSvc-->>API: { reservation }
    API-->>WebApp: 201 Created
    WebApp-->>Client: Affiche confirmation
    
    Note over EventBus: Communication asynchrone
    
    EventBus->>InvSvc: Event: reservation.created
    InvSvc->>DB: UPDATE stock SET reserved = reserved + 1
    DB-->>InvSvc: Stock mis à jour
    
    EventBus->>NotifSvc: Event: reservation.created
    NotifSvc->>NotifSvc: sendReservationConfirmation()
    NotifSvc-->>Client: Email de confirmation
    
    EventBus->>PaySvc: Event: reservation.created
    PaySvc->>PaySvc: createPaymentIntent()
    Note over PaySvc: Prépare paiement pour plus tard

Étapes :

Validation : Dates cohérentes
Vérification : Disponibilité via Inventory Service (sync)
Calcul : Prix de la réservation
Création : Insertion en base
Event : Publication asynchrone
Asynchrone : Inventory met à jour stock, Notification envoie email, Payment prépare paiement

Diagramme d'Infrastructure

Objectif : Vue du déploiement et de l'infrastructure.

graph TB
    subgraph "Client"
        Browser[Browser]
    end

    subgraph "Vercel Edge Network"
        CDN[CDN / Edge Cache]
        SSR[Next.js SSR]
    end

    subgraph "Application Next.js (Vercel)"
        WebApp[Pages & Components]
        APIGateway[API Routes / BFF]
        
        subgraph "Microservices (Colocalisés)"
            AuthSvc[Auth Service]
            CatalogueSvc[Catalogue Service]
            ReservationSvc[Reservation Service]
            InventorySvc[Inventory Service]
            PaymentSvc[Payment Service]
            NotificationSvc[Notification Service]
        end
    end

    subgraph "Supabase Cloud"
        PostgreSQL[(PostgreSQL)]
        SupabaseAuth[Supabase Auth]
        RealtimeChannels[Realtime Channels]
        Storage[Storage]
        EdgeFunctions[Edge Functions]
    end

    subgraph "Services Externes"
        Stripe[Stripe API]
        EmailProvider[Service Email]
    end

    Browser -->|HTTPS| CDN
    CDN -->|Cache Miss| SSR
    SSR --> WebApp
    WebApp --> APIGateway
    
    APIGateway --> AuthSvc
    APIGateway --> CatalogueSvc
    APIGateway --> ReservationSvc
    APIGateway --> InventorySvc
    APIGateway --> PaymentSvc
    
    AuthSvc -.->|Auth API| SupabaseAuth
    CatalogueSvc -->|SQL| PostgreSQL
    ReservationSvc -->|SQL| PostgreSQL
    InventorySvc -->|SQL| PostgreSQL
    PaymentSvc -->|SQL| PostgreSQL
    
    ReservationSvc -->|Publish| RealtimeChannels
    InventorySvc -->|Subscribe| RealtimeChannels
    NotificationSvc -->|Subscribe| RealtimeChannels
    
    CatalogueSvc -->|Upload| Storage
    PaymentSvc -->|API| Stripe
    NotificationSvc -->|API| EmailProvider
    
    style Browser fill:#e1f5ff
    style CDN fill:#fff4e6
    style SSR fill:#fff4e6
    style PostgreSQL fill:#e8f5e9
    style RealtimeChannels fill:#f3e5f5
    style Stripe fill:#ede7f6
    style EmailProvider fill:#ede7f6

Composants :

Vercel Edge : CDN + SSR
Next.js App : WebApp + API Gateway + Microservices (colocalisés)
Supabase : PostgreSQL + Auth + Realtime + Storage
Services externes : Stripe (paiements), Email Provider

Flux :

Browser → Vercel CDN (cache)
CDN Miss → Next.js SSR
SSR → API Gateway → Microservices
Microservices → Supabase (PostgreSQL, Realtime, Storage)
Microservices → Services externes (Stripe, Email)

Comparaison Legacy vs Moderne

graph LR
    subgraph "Architecture Legacy (Monolithe)"
        LegacyClient[Client]
        LegacyServer[Serveur Express]
        LegacySQLite[(SQLite)]
        
        LegacyClient -->|HTTP| LegacyServer
        LegacyServer -->|Tout dans un fichier| LegacySQLite
    end
    
    subgraph "Architecture Moderne (Microservices Hybride)"
        ModerneClient[Client]
        NextJS[Next.js SSR]
        APIGateway[API Gateway]
        
        subgraph Microservices
            MS1[Auth]
            MS2[Catalogue]
            MS3[Reservation]
            MS4[Inventory]
            MS5[Payment]
            MS6[Notification]
        end
        
        EventBus[Event Bus]
        PostgreSQL[(PostgreSQL)]
        
        ModerneClient -->|HTTPS| NextJS
        NextJS --> APIGateway
        APIGateway --> MS1
        APIGateway --> MS2
        APIGateway --> MS3
        APIGateway --> MS4
        APIGateway --> MS5
        
        MS3 -->|Publish| EventBus
        EventBus -->|Subscribe| MS4
        EventBus -->|Subscribe| MS6
        
        MS2 --> PostgreSQL
        MS3 --> PostgreSQL
        MS4 --> PostgreSQL
        MS5 --> PostgreSQL
    end
    
    style LegacyServer fill:#ffcdd2
    style LegacySQLite fill:#ffcdd2
    style NextJS fill:#c8e6c9
    style APIGateway fill:#c8e6c9
    style EventBus fill:#b3e5fc
    style PostgreSQL fill:#c8e6c9

Légende des Diagrammes

Symbole	Signification
🟦 Rectangle bleu	Personne/Acteur
🟩 Rectangle vert	Système interne
🟧 Rectangle orange	Système externe
🗄️ Cylindre	Base de données
→ Flèche pleine	Communication synchrone
⇢ Flèche pointillée	Communication asynchrone

Outils de Visualisation

Mermaid Live Editor :

URL : https://mermaid.live/
Permet de tester et exporter les diagrammes

PlantUML (alternative) :

Pour des diagrammes C4 plus complexes
Intégration VS Code via extension

Structurizr (alternative premium) :

Diagrammes C4 officiels
DSL spécialisé

Prochaines Étapes

✅ Diagrammes C4 créés (Context, Container, Component)
⏭️ Créer diagrammes spécifiques par Use Case
⏭️ Ajouter diagrammes d'états (State Machine)
⏭️ Documenter patterns de communication (Request-Response, Pub-Sub)

Mise à jour : Octobre 2025

16 KiB Raw Permalink Blame History