ansiblenginx/app/bricolociaac/apps/modern-app/docs/LOGICAL_ARCHITECTURE.md

Architecture Logique - BricoLoc Moderne

Version : 1.0
Date : 31 Octobre 2025
Projet : BricoLoc - Application Moderne de Location d'Outils

---

Vue d'Ensemble

BricoLoc Moderne suit une architecture microservices hybride avec Clean Architecture par service. L'application est construite sur une stack serverless moderne avec Next.js 14 et Supabase.

graph TB
    subgraph "Client Layer"
        UI[Next.js App Router]
        Components[React Components]
    end
    
    subgraph "Application Layer"
        Auth[Auth Service]
        Catalogue[Catalogue Service]
        Reservation[Reservation Service]
        Inventory[Inventory Service]
        Payment[Payment Service]
        Notification[Notification Service]
    end
    
    subgraph "Infrastructure Layer"
        Supabase[(Supabase)]
        Storage[Supabase Storage]
        Realtime[Realtime Subscriptions]
    end
    
    UI --> Auth
    UI --> Catalogue
    UI --> Reservation
    UI --> Inventory
    UI --> Payment
    UI --> Notification
    
    Auth --> Supabase
    Catalogue --> Supabase
    Reservation --> Supabase
    Inventory --> Supabase
    Payment --> Supabase
    Notification --> Supabase
    
    Catalogue --> Storage
    Reservation --> Realtime
    Notification --> Realtime

---

1. Architecture Microservices

1.1 Décomposition en Services

L'application est divisée en 6 microservices autonomes :

Auth Service 🔐

• Responsabilité : Authentification, autorisation, gestion des utilisateurs
• Bounded Context : Identité utilisateur, sessions, rôles
• Technologies : Supabase Auth, JWT
• API :
  • POST /auth/register
  • POST /auth/login
  • POST /auth/logout
  • GET /auth/profile
  • PUT /auth/profile

Catalogue Service 📦

• Responsabilité : Gestion du catalogue d'outils, catégories, recherche
• Bounded Context : Outils, catégories, spécifications techniques
• Technologies : Supabase PostgreSQL, Full-text search
• API :
  • GET /outils
  • GET /outils/:id
  • GET /outils/search?q=...
  • GET /categories
  • GET /categories/:id/outils

Reservation Service 📅

• Responsabilité : Gestion des réservations, calendrier, disponibilités
• Bounded Context : Réservations, périodes, statuts
• Technologies : Supabase PostgreSQL, Realtime
• API :
  • POST /reservations
  • GET /reservations
  • GET /reservations/:id
  • PUT /reservations/:id
  • DELETE /reservations/:id
  • GET /reservations/availability?tool=...&from=...&to=...

Inventory Service 📊

• Responsabilité : Gestion des stocks, entrepôts, disponibilités
• Bounded Context : Stocks, entrepôts, mouvements
• Technologies : Supabase PostgreSQL
• API :
  • GET /inventory
  • GET /inventory/:toolId
  • GET /entrepots
  • GET /entrepots/:id/stock

Payment Service 💳

• Responsabilité : Gestion des paiements, transactions, cautions
• Bounded Context : Transactions, paiements, remboursements
• Technologies : Stripe, Supabase PostgreSQL
• API :
  • POST /payments/create-intent
  • POST /payments/confirm
  • GET /payments/:id
  • POST /payments/:id/refund

Notification Service 🔔

• Responsabilité : Notifications en temps réel, emails, alertes
• Bounded Context : Notifications, préférences utilisateur
• Technologies : Supabase Realtime, Email service
• API :
  • GET /notifications
  • PUT /notifications/:id/read
  • DELETE /notifications/:id
  • GET /notifications/preferences

---

2. Clean Architecture par Service

Chaque service suit Clean Architecture avec 3 couches distinctes :

graph LR
    subgraph "Service Architecture"
        Domain[Domain Layer]
        Application[Application Layer]
        Infrastructure[Infrastructure Layer]
    end
    
    Infrastructure --> Application
    Application --> Domain

2.1 Domain Layer (Cœur Métier)

Responsabilité : Logique métier pure, indépendante de toute infrastructure

Composants :

• Entities : Objets métier avec identité
• Value Objects : Objets immuables sans identité (Email, Money, DateRange)
• Domain Events : Événements métier
• Repository Interfaces : Contrats de persistance
• Business Rules : Règles métier pures

Exemple : src/services/reservation/domain/

domain/
├── entities/
│   └── reservation.entity.ts
├── value-objects/
│   ├── date-range.ts
│   ├── price.ts
│   └── reservation-status.ts
├── repositories/
│   └── reservation.repository.interface.ts
└── events/
    └── reservation-created.event.ts

2.2 Application Layer (Use Cases)

Responsabilité : Orchestration de la logique métier, cas d'utilisation

Composants :

• Use Cases : Scénarios d'utilisation (CreateReservationUseCase)
• Services : Services applicatifs (PriceCalculatorService)
• DTOs : Data Transfer Objects
• Mappers : Conversion Entity ↔ DTO

Exemple : src/services/reservation/application/

application/
├── use-cases/
│   ├── create-reservation.use-case.ts
│   ├── cancel-reservation.use-case.ts
│   └── check-availability.use-case.ts
├── services/
│   └── price-calculator.service.ts
└── dtos/
    └── create-reservation.dto.ts

2.3 Infrastructure Layer (Implémentation)

Responsabilité : Détails techniques, frameworks, bases de données

Composants :

• Repositories : Implémentation des repositories
• External Services : Intégrations externes (Stripe, Email)
• API Routes : Next.js API routes
• Supabase Clients : Clients de base de données

Exemple : src/services/reservation/infrastructure/

infrastructure/
├── repositories/
│   └── supabase-reservation.repository.ts
├── external/
│   └── stripe-payment-gateway.ts
└── api/
    └── reservations.route.ts

---

3. Flux de Données

3.1 Flux de Lecture (Query)

sequenceDiagram
    participant User
    participant UI as Next.js UI
    participant UseCase as Use Case
    participant Repo as Repository
    participant DB as Supabase

    User->>UI: Demande données
    UI->>UseCase: Execute query
    UseCase->>Repo: FindById/FindAll
    Repo->>DB: SELECT query
    DB-->>Repo: Raw data
    Repo-->>UseCase: Domain entity
    UseCase-->>UI: DTO
    UI-->>User: Affichage

3.2 Flux d'Écriture (Command)

sequenceDiagram
    participant User
    participant UI as Next.js UI
    participant UseCase as Use Case
    participant Domain as Domain Entity
    participant Repo as Repository
    participant DB as Supabase
    participant Event as Event Bus

    User->>UI: Soumet formulaire
    UI->>UseCase: Execute command
    UseCase->>Domain: Create/Update entity
    Domain->>Domain: Validate business rules
    UseCase->>Repo: Save entity
    Repo->>DB: INSERT/UPDATE
    DB-->>Repo: Success
    Repo-->>UseCase: Saved entity
    UseCase->>Event: Publish domain event
    UseCase-->>UI: Result
    UI-->>User: Confirmation

---

4. Communication entre Services

4.1 Stratégie de Communication

Les services communiquent via 2 patterns :

Synchrone : API REST (Next.js API Routes)

• Utilisé pour : Requêtes/Réponses immédiates
• Exemple : Catalogue → Inventory (check stock)

Asynchrone : Event Bus (Supabase Realtime)

• Utilisé pour : Notifications, updates temps réel
• Exemple : Reservation → Notification (nouvelle réservation)

graph LR
    subgraph "Synchronous Communication"
        S1[Service A] -->|REST API| S2[Service B]
    end
    
    subgraph "Asynchronous Communication"
        S3[Service C] -->|Event| EB[Event Bus]
        EB -->|Subscribe| S4[Service D]
        EB -->|Subscribe| S5[Service E]
    end

4.2 Event Bus

Implémentation : Supabase Realtime (PostgreSQL NOTIFY/LISTEN)

Events Types :

• reservation.created
• reservation.confirmed
• reservation.cancelled
• payment.succeeded
• inventory.updated

Exemple :

// Publisher
eventBus.publish('reservation.created', {
  reservationId: '...',
  userId: '...',
  toolId: '...',
  dateRange: {...}
})

// Subscriber
eventBus.subscribe('reservation.created', async (event) => {
  // Send notification
  await notificationService.sendReservationConfirmation(event.data)
})

---

5. Gestion de l'État

5.1 État Client (Frontend)

Technologies :

• Zustand : État global partagé (auth, panier)
• React Query : Cache et synchronisation server state
• React Context : État local partagé (theme, locale)

// Zustand Store (Global State)
interface AuthStore {
  user: User | null
  login: (credentials) => Promise<void>
  logout: () => Promise<void>
}

// React Query (Server State)
const { data: tools } = useQuery({
  queryKey: ['tools'],
  queryFn: fetchTools
})

5.2 État Serveur (Backend)

Technologies :

• Supabase PostgreSQL : Source de vérité
• Row Level Security : Sécurité au niveau base de données
• Realtime Subscriptions : Synchronisation temps réel

---

6. Sécurité

6.1 Architecture de Sécurité

graph TB
    subgraph "Security Layers"
        Client[Client Layer]
        API[API Layer]
        Domain[Domain Layer]
        DB[Database Layer]
    end
    
    Client -->|JWT Token| API
    API -->|Authorization| Domain
    Domain -->|RLS Policies| DB
    
    CSP[Content Security Policy] --> Client
    RateLimit[Rate Limiting] --> API
    Validation[Input Validation] --> Domain
    RLS[Row Level Security] --> DB

6.2 Principes de Sécurité

1. Defense in Depth : Sécurité en couches
2. Least Privilege : Permissions minimales
3. Zero Trust : Vérification à chaque couche
4. Secure by Default : Sécurisé par défaut

6.3 Implémentation

• Authentication : Supabase Auth (JWT)
• Authorization : RLS policies + middleware Next.js
• Input Validation : Zod schemas
• Output Encoding : React auto-escape
• CSRF Protection : Next.js built-in
• Rate Limiting : API routes middleware

---

7. Performance et Scalabilité

7.1 Stratégies d'Optimisation

Frontend :

• Server Components (Next.js 14)
• Code Splitting automatique
• Image Optimization (next/image)
• Static Generation quand possible
• CDN Edge caching

Backend :

• Database Indexing (Supabase)
• Connection Pooling
• Query Optimization
• Caching (React Query)

7.2 Scalabilité

graph TB
    subgraph "Horizontal Scaling"
        LB[Load Balancer<br/>Vercel Edge]
        LB --> FN1[Function 1]
        LB --> FN2[Function 2]
        LB --> FN3[Function N]
    end
    
    subgraph "Vertical Scaling"
        DB[(Supabase<br/>PostgreSQL)]
    end
    
    FN1 --> DB
    FN2 --> DB
    FN3 --> DB

---

8. Déploiement et Infrastructure

8.1 Architecture de Déploiement

graph TB
    subgraph "Production Environment"
        DNS[Vercel DNS]
        Edge[Vercel Edge Network]
        Functions[Serverless Functions]
        Supabase[(Supabase Cloud)]
    end
    
    User --> DNS
    DNS --> Edge
    Edge --> Functions
    Functions --> Supabase

8.2 Environnements

Environnement	Usage	URL
Development	Local dev	http://localhost:3000
Staging	Tests pré-prod	preview-*.vercel.app
Production	Production	bricoloc-moderne.vercel.app

---

9. Monitoring et Observabilité

9.1 Logging

• Application Logs : Vercel Logs
• Database Logs : Supabase Logs
• Error Tracking : Sentry (futur)

9.2 Metrics

• Web Vitals : Vercel Analytics
• API Performance : Response times, error rates
• Database Performance : Query times, connection pool

9.3 Alerting

• Uptime Monitoring : Vercel Status
• Error Rate : Sentry alerts (futur)
• Performance Degradation : Custom alerts

---

10. Évolution Future

10.1 Roadmap Technique

Phase 2 (Semaines 11-15) :

• Optimisations performance avancées
• Analytics détaillés
• A/B Testing framework

Phase 3 (Post-MVP) :

• Mobile apps (React Native)
• Offline-first capabilities
• Advanced search (Elasticsearch)

10.2 Debt Technique

• Implémenter cache Redis pour hot data
• Ajouter monitoring APM complet
• Implémenter circuit breakers
• Ajouter tests de charge

---

Conclusion

Cette architecture logique fournit une base solide, maintenable et scalable pour BricoLoc Moderne. Elle suit les meilleures pratiques modernes tout en restant pragmatique et adaptée au contexte du projet.

Prochaine révision : Semaine 10 (après première release)