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.
514 lines
13 KiB
Markdown
514 lines
13 KiB
Markdown
# 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)
|