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.

```mermaid
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 :

```mermaid
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)

```mermaid
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)

```mermaid
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)

```mermaid
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** :
```typescript
// 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)

```typescript
// 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é

```mermaid
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é

```mermaid
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

```mermaid
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)