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.
454 lines
16 KiB
Markdown
454 lines
16 KiB
Markdown
# 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
|
|
|
|
1. [Niveau 1 : Diagramme de Contexte](#niveau-1--diagramme-de-contexte)
|
|
2. [Niveau 2 : Diagramme de Conteneurs](#niveau-2--diagramme-de-conteneurs)
|
|
3. [Niveau 3 : Diagramme de Composants (Reservation Service)](#niveau-3--diagramme-de-composants-reservation-service)
|
|
4. [Diagramme de Séquence : Créer une Réservation](#diagramme-de-séquence--créer-une-réservation)
|
|
5. [Diagramme d'Infrastructure](#diagramme-dinfrastructure)
|
|
|
|
---
|
|
|
|
## Niveau 1 : Diagramme de Contexte
|
|
|
|
**Objectif** : Vue d'ensemble du système et de son interaction avec les acteurs externes.
|
|
|
|
```mermaid
|
|
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).
|
|
|
|
```mermaid
|
|
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).
|
|
|
|
```mermaid
|
|
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** :
|
|
1. **Application Layer** : Controllers, Services, Use Cases
|
|
2. **Domain Layer** : Entités, Factories, Interfaces, Business Rules
|
|
3. **Infrastructure Layer** : Repositories, Event Publishers
|
|
|
|
**Flux** :
|
|
1. API Route → Controller
|
|
2. Controller → Service
|
|
3. Service → Use Case
|
|
4. Use Case → Factory/Rules → Repository
|
|
5. Repository → Database
|
|
6. 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).
|
|
|
|
```mermaid
|
|
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** :
|
|
1. **Validation** : Dates cohérentes
|
|
2. **Vérification** : Disponibilité via Inventory Service (sync)
|
|
3. **Calcul** : Prix de la réservation
|
|
4. **Création** : Insertion en base
|
|
5. **Event** : Publication asynchrone
|
|
6. **Asynchrone** : Inventory met à jour stock, Notification envoie email, Payment prépare paiement
|
|
|
|
---
|
|
|
|
## Diagramme d'Infrastructure
|
|
|
|
**Objectif** : Vue du déploiement et de l'infrastructure.
|
|
|
|
```mermaid
|
|
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** :
|
|
1. Browser → Vercel CDN (cache)
|
|
2. CDN Miss → Next.js SSR
|
|
3. SSR → API Gateway → Microservices
|
|
4. Microservices → Supabase (PostgreSQL, Realtime, Storage)
|
|
5. Microservices → Services externes (Stripe, Email)
|
|
|
|
---
|
|
|
|
## Comparaison Legacy vs Moderne
|
|
|
|
```mermaid
|
|
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
|
|
|
|
1. ✅ Diagrammes C4 créés (Context, Container, Component)
|
|
2. ⏭️ Créer diagrammes spécifiques par Use Case
|
|
3. ⏭️ Ajouter diagrammes d'états (State Machine)
|
|
4. ⏭️ Documenter patterns de communication (Request-Response, Pub-Sub)
|
|
|
|
---
|
|
|
|
**Mise à jour** : Octobre 2025
|