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

🗺️ Roadmap Application Moderne BricoLoc

Objectif : Créer une application moderne avec architecture microservices hybride démontrant les bonnes pratiques architecturales et les patterns de conception avancés.

Durée : 5 semaines (Semaines 5-9 du projet global)
Effort : 135 heures
Stack technique : Next.js 14, TypeScript, Supabase, Tailwind CSS, shadcn/ui

---

📊 État d'Avancement

Dernière mise à jour : 2 Novembre 2025

Phase	Statut	Progression	Temps estimé
Semaine 5 - Setup & Structure	✅ Terminé	100%	20h
Semaine 6 - Auth Service	🔲 À démarrer	0%	20h
Semaine 7 - Catalogue Service	🔲 À démarrer	0%	25h
Semaine 8 - Inventory Service	🔲 À démarrer	0%	25h
Semaine 9 - Reservation/Payment	🔲 À démarrer	0%	25h
Semaine 10 - Finitions	🔲 À démarrer	0%	20h

Progression globale : ■■⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜ 17% (1/6 phases)

---

🎯 Objectifs Clés

Démontrer les Bonnes Pratiques

1. ✅ Architecture Microservices Hybride

   • Décomposition en services autonomes
   • Communication REST + Event-Driven
   • API Gateway / BFF pattern

2. ✅ Clean Architecture par Service

   • Domain Layer (Entities, Business Rules)
   • Application Layer (Use Cases, Services)
   • Infrastructure Layer (Repositories, External APIs)
   • Separation of Concerns stricte

3. ✅ Design Patterns

   • Repository Pattern
   • Service Layer Pattern
   • Dependency Injection
   • Factory Pattern
   • Observer Pattern (Event Bus)

4. ✅ Principes SOLID

   • Single Responsibility Principle
   • Open/Closed Principle
   • Liskov Substitution Principle
   • Interface Segregation Principle
   • Dependency Inversion Principle

5. ✅ Tests & Qualité

   • Tests unitaires (80%+ coverage)
   • Tests d'intégration
   • Tests E2E (Playwright)
   • TypeScript strict mode
   • ESLint + Prettier

6. ✅ Performance & UX

   • Server-Side Rendering (SSR)
   • Static Site Generation (SSG)
   • Optimistic UI updates
   • Real-time updates (Supabase Realtime)
   • Lighthouse score > 90

---

📋 Livrables Attendus

Livrables Alignés avec le Cahier des Charges

D'après le document livrables.md, nous devons fournir :

1. Schéma de la Couche Applicative du SI ✅

• Localisation : docs/architecture/c4-diagrams.md
• Contenu : Diagrammes C4 montrant les applications et leurs interactions
• Status : ✅ Complété (Sprint 0)

2. Démarche de Conception de l'Architecture ✅

• Localisation : apps/modern-app/docs/ARCHITECTURE_DECISION_PROCESS.md
• Contenu :
  • Analyse des besoins et contraintes
  • Identification des exigences non fonctionnelles
  • Évaluation des styles architecturaux
  • Justification des choix
• Status : ✅ Complété (Semaine 5) - Voir ADRs dans docs/architecture/ADR/

3. Liste des Exigences Non Fonctionnelles ✅

• Localisation : apps/modern-app/docs/NON_FUNCTIONAL_REQUIREMENTS.md
• Contenu :
  • Performance (temps de réponse, throughput)
  • Scalabilité (horizontal, vertical)
  • Maintenabilité (modularité, testabilité)
  • Sécurité (authentification, autorisation, chiffrement)
  • Disponibilité (uptime, résilience)
  • Utilisabilité (UX, accessibilité)
• Status : ✅ Complété (Semaine 5)

4. Schéma d'Architecture Logique ✅

• Localisation : apps/modern-app/docs/LOGICAL_ARCHITECTURE.md
• Contenu :
  • Décomposition en composants métiers
  • Interactions entre composants
  • Dépendances fonctionnelles
  • Sans détails techniques (technos, déploiement)
• Status : ✅ Complété (Semaine 5)

5. Comparaison des Styles Architecturaux ✅

• Localisation : apps/modern-app/docs/ARCHITECTURE_STYLES_COMPARISON.md
• Contenu :
  • Monolithe vs Microservices
  • Layered vs Clean Architecture
  • REST vs GraphQL vs gRPC
  • Event-Driven vs Request-Response
  • Justification des choix retenus
• Status : ✅ Complété (Semaine 5)

6. Template de Matrice de Choix Technologique ✅

• Localisation : apps/modern-app/docs/TECHNOLOGY_DECISION_MATRIX.md
• Contenu :
  • Critères d'évaluation (pondérés)
  • Système de cotation (1-5 étoiles)
  • Matrices complétées pour :
    • Framework Frontend (Next.js vs Remix vs Nuxt)
    • Backend (Supabase vs Firebase vs AWS Amplify)
    • Base de données (PostgreSQL vs MongoDB vs MySQL)
    • Event Bus (Supabase Realtime vs Redis Pub/Sub vs Kafka)
• Status : ✅ Complété (Semaine 5)

7. Points Faibles du SI Actuel 🚧

• Localisation : docs/SI_WEAKNESSES_ANALYSIS.md
• Contenu :
  • Liste des points faibles identifiés
  • Impact sur l'évolution du SI
  • Justifications techniques
  • Propositions d'amélioration
• Status : 🔲 À créer (Semaine 5)

8. Bilan sur l'Organisation du Groupe 🚧

• Localisation : docs/TEAM_RETROSPECTIVE.md
• Contenu :
  • Points forts de l'équipe
  • Axes d'amélioration
  • Méthode de travail
  • Communication et collaboration
• Status : 🔲 À créer (Semaine 10)

9. Support de Présentation (PowerPoint) 🚧

• Localisation : docs/presentation/BricoLoc_Presentation.pptx
• Contenu : Synthèse de tous les éléments ci-dessus
• Status : 🔲 À créer (Semaine 10)

---

🏗️ Architecture Technique

Stack Complète

# Frontend
Framework: Next.js 14 (App Router)
Language: TypeScript 5.3 (strict mode)
UI Library: React 18
Styling: Tailwind CSS 3.4
Components: shadcn/ui
State Management: Zustand + React Query
Forms: React Hook Form + Zod

# Backend (BFF + Microservices)
API: Next.js API Routes (BFF pattern)
Microservices: Clean Architecture par service
Communication: REST + Event-Driven

# Database & Backend Services
BaaS: Supabase
Database: PostgreSQL 15
Auth: Supabase Auth (JWT)
Storage: Supabase Storage
Realtime: Supabase Realtime (WebSockets)
Functions: Supabase Edge Functions (optionnel)

# Testing
Unit Tests: Jest + React Testing Library
Integration Tests: Jest + Supertest
E2E Tests: Playwright
Coverage: > 80%

# DevOps
Version Control: Git + GitHub
CI/CD: GitHub Actions
Deployment: Vercel (Next.js) + Supabase (hébergé)
Monitoring: Vercel Analytics + Sentry (optionnel)

# Code Quality
Linting: ESLint (strict)
Formatting: Prettier
Type Checking: TypeScript strict mode
Git Hooks: Husky + lint-staged

---

📁 Structure du Projet

apps/modern-app/
├── src/
│   ├── app/                          # Next.js App Router
│   │   ├── (auth)/                   # Auth routes group
│   │   │   ├── login/
│   │   │   └── register/
│   │   ├── (main)/                   # Main app routes group
│   │   │   ├── outils/
│   │   │   ├── reservations/
│   │   │   └── admin/
│   │   ├── api/                      # API Routes (BFF)
│   │   │   ├── auth/
│   │   │   ├── catalogue/
│   │   │   ├── reservations/
│   │   │   ├── inventory/
│   │   │   ├── payment/
│   │   │   └── notifications/
│   │   ├── layout.tsx
│   │   └── page.tsx
│   │
│   ├── services/                     # Microservices (Business Logic)
│   │   ├── auth/
│   │   │   ├── domain/
│   │   │   │   ├── entities/
│   │   │   │   │   └── user.entity.ts
│   │   │   │   └── repositories/
│   │   │   │       └── auth.repository.interface.ts
│   │   │   ├── application/
│   │   │   │   ├── use-cases/
│   │   │   │   │   ├── register-user.use-case.ts
│   │   │   │   │   └── login-user.use-case.ts
│   │   │   │   └── services/
│   │   │   │       └── auth.service.ts
│   │   │   └── infrastructure/
│   │   │       └── repositories/
│   │   │           └── supabase-auth.repository.ts
│   │   │
│   │   ├── catalogue/
│   │   │   ├── domain/
│   │   │   ├── application/
│   │   │   └── infrastructure/
│   │   │
│   │   ├── reservation/
│   │   │   ├── domain/
│   │   │   ├── application/
│   │   │   └── infrastructure/
│   │   │
│   │   ├── inventory/
│   │   │   ├── domain/
│   │   │   ├── application/
│   │   │   └── infrastructure/
│   │   │
│   │   ├── payment/
│   │   │   ├── domain/
│   │   │   ├── application/
│   │   │   └── infrastructure/
│   │   │
│   │   └── notification/
│   │       ├── domain/
│   │       ├── application/
│   │       └── infrastructure/
│   │
│   ├── shared/                       # Code partagé
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   └── value-objects/
│   │   ├── infrastructure/
│   │   │   ├── di/                   # Dependency Injection
│   │   │   ├── events/               # Event Bus
│   │   │   └── supabase/
│   │   └── utils/
│   │
│   ├── components/                   # UI Components
│   │   ├── ui/                       # shadcn/ui components
│   │   ├── features/                 # Feature-specific components
│   │   └── layouts/
│   │
│   ├── hooks/                        # Custom React Hooks
│   ├── lib/                          # Utility libraries
│   └── types/                        # TypeScript types
│
├── public/
│   ├── images/
│   └── fonts/
│
├── docs/
│   ├── ROADMAP_MODERN.md            # Ce fichier
│   ├── ARCHITECTURE_DECISION_PROCESS.md
│   ├── NON_FUNCTIONAL_REQUIREMENTS.md
│   ├── LOGICAL_ARCHITECTURE.md
│   ├── ARCHITECTURE_STYLES_COMPARISON.md
│   └── TECHNOLOGY_DECISION_MATRIX.md
│
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
│
├── .github/
│   └── workflows/
│       └── ci.yml
│
├── next.config.js
├── tailwind.config.ts
├── tsconfig.json
├── jest.config.js
├── playwright.config.ts
├── .eslintrc.json
├── .prettierrc
└── package.json

---

📖 Documentation Détaillée par Semaine

Pour éviter un document trop long, la roadmap détaillée est divisée en plusieurs fichiers :

• 📄 Semaine 5 - Setup & Structure
• 📄 Semaine 6 - Auth Service
• 📄 Semaine 7 - Catalogue Service
• 📄 Semaine 8 - Inventory Service
• 📄 Semaine 9 - Reservation & Payment
• 📄 Semaine 10 - Finitions & Présentation

---

🎯 User Stories - Application Moderne

ID	User Story	Semaine	Priorité	Statut
US-M01	En tant qu'utilisateur, je peux créer un compte avec validation email	6	🔴 Critique	🔲
US-M02	En tant qu'utilisateur, je peux me connecter (+ OAuth Google)	6	🔴 Critique	🔲
US-M03	En tant que visiteur, je peux rechercher des outils avec filtres avancés	7	🔴 Critique	🔲
US-M04	En tant qu'utilisateur, je peux voir les détails d'un outil avec galerie d'images	7	🔴 Critique	🔲
US-M05	En tant qu'admin, je peux gérer les outils (CRUD complet)	7	🟠 Important	🔲
US-M06	En tant qu'utilisateur, je vois la disponibilité en temps réel	8	🔴 Critique	🔲
US-M07	En tant qu'admin, je peux gérer les stocks par entrepôt	8	🟠 Important	🔲
US-M08	En tant qu'utilisateur, je peux créer une réservation avec vérification	9	🔴 Critique	🔲
US-M09	En tant qu'utilisateur, je peux payer ma réservation (Stripe)	9	🔴 Critique	🔲
US-M10	En tant qu'utilisateur, je reçois un email de confirmation	9	🟠 Important	🔲
US-M11	En tant qu'utilisateur, je peux laisser un avis sur un outil	-	🟢 Optionnel	⏸️
US-M12	En tant qu'admin, je vois un dashboard analytics	-	🟢 Optionnel	⏸️

---

🎨 Principes de Design & UX

Design System

Basé sur shadcn/ui (Radix UI + Tailwind CSS)

// Palette de couleurs
const colors = {
  primary: {
    DEFAULT: '#3b82f6', // blue-500
    dark: '#1e40af',    // blue-800
    light: '#93c5fd',   // blue-300
  },
  secondary: {
    DEFAULT: '#64748b', // slate-500
  },
  success: '#22c55e',   // green-500
  warning: '#f59e0b',   // amber-500
  error: '#ef4444',     // red-500
}

// Typography
const typography = {
  fontFamily: {
    sans: ['Inter', 'system-ui', 'sans-serif'],
    mono: ['Fira Code', 'monospace'],
  },
  fontSize: {
    xs: '0.75rem',    // 12px
    sm: '0.875rem',   // 14px
    base: '1rem',     // 16px
    lg: '1.125rem',   // 18px
    xl: '1.25rem',    // 20px
    '2xl': '1.5rem',  // 24px
    '3xl': '1.875rem',// 30px
    '4xl': '2.25rem', // 36px
  }
}

Composants UI Réutilisables

Tous les composants suivent les principes shadcn/ui :

• Accessibilité (ARIA, keyboard navigation)
• Responsive (mobile-first)
• Themable (dark mode support)
• Type-safe (TypeScript)

Liste des composants à implémenter :

• ✅ Button, Input, Select, Checkbox, Radio
• ✅ Card, Dialog, Sheet, Popover, Tooltip
• ✅ Table, Pagination, Tabs
• ✅ Form (React Hook Form + Zod)
• ✅ Toast (notifications)
• ✅ Badge, Avatar, Separator
• ✅ Calendar, DatePicker

---

🧪 Stratégie de Tests

Tests Unitaires (Jest)

Coverage target : > 80%

// Exemple : tests d'un Use Case
describe('CreateReservationUseCase', () => {
  let useCase: CreateReservationUseCase
  let mockReservationRepo: jest.Mocked<IReservationRepository>
  let mockInventoryService: jest.Mocked<InventoryService>

  beforeEach(() => {
    mockReservationRepo = createMockReservationRepository()
    mockInventoryService = createMockInventoryService()
    useCase = new CreateReservationUseCase(
      mockReservationRepo,
      mockInventoryService
    )
  })

  it('should create a reservation when stock is available', async () => {
    // Arrange
    mockInventoryService.checkAvailability.mockResolvedValue(true)
    
    // Act
    const result = await useCase.execute({
      outilId: '123',
      userId: 'user1',
      dateDebut: '2025-11-01',
      dateFin: '2025-11-05'
    })
    
    // Assert
    expect(result.isSuccess).toBe(true)
    expect(mockReservationRepo.create).toHaveBeenCalledTimes(1)
  })

  it('should fail when stock is unavailable', async () => {
    // Arrange
    mockInventoryService.checkAvailability.mockResolvedValue(false)
    
    // Act
    const result = await useCase.execute({...})
    
    // Assert
    expect(result.isFailure).toBe(true)
    expect(result.error).toBe('Stock unavailable')
  })
})

Tests d'Intégration

Tests des API Routes avec base de données réelle (Supabase local)

describe('POST /api/reservations', () => {
  beforeAll(async () => {
    await setupTestDatabase()
  })

  afterAll(async () => {
    await cleanupTestDatabase()
  })

  it('should create a reservation with valid data', async () => {
    const response = await fetch('/api/reservations', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${testToken}`
      },
      body: JSON.stringify({
        outilId: 'test-outil-1',
        dateDebut: '2025-11-01',
        dateFin: '2025-11-05'
      })
    })

    expect(response.status).toBe(201)
    const data = await response.json()
    expect(data).toHaveProperty('id')
    expect(data.statut).toBe('en_attente_paiement')
  })
})

Tests E2E (Playwright)

Tests du parcours utilisateur complet

test('Parcours complet de réservation', async ({ page }) => {
  // 1. Connexion
  await page.goto('/login')
  await page.fill('[name="email"]', 'test@example.com')
  await page.fill('[name="password"]', 'password123')
  await page.click('button[type="submit"]')
  
  // 2. Recherche d'outil
  await page.goto('/outils')
  await page.fill('[name="search"]', 'Perceuse')
  await page.click('button:has-text("Rechercher")')
  
  // 3. Sélection d'outil
  await page.click('article:has-text("Perceuse Bosch") a')
  
  // 4. Création de réservation
  await page.click('button:has-text("Réserver")')
  await page.fill('[name="dateDebut"]', '2025-11-01')
  await page.fill('[name="dateFin"]', '2025-11-05')
  await page.selectOption('[name="entrepotId"]', 'toulouse')
  await page.click('button:has-text("Confirmer")')
  
  // 5. Vérification
  await expect(page.locator('text=Réservation créée')).toBeVisible()
})

---

📊 Métriques de Succès

Métriques Techniques

Métrique	Objectif	Mesure
Lighthouse Performance	> 90	Lighthouse CI
Lighthouse Accessibility	> 95	Lighthouse CI
Lighthouse Best Practices	> 95	Lighthouse CI
Lighthouse SEO	> 90	Lighthouse CI
Tests Coverage	> 80%	Jest Coverage
TypeScript Strict	100%	tsc --noEmit
ESLint Errors	0	ESLint
Bundle Size (First Load JS)	< 200 KB	Next.js Build
Time to Interactive (TTI)	< 2s	Lighthouse
First Contentful Paint (FCP)	< 1s	Lighthouse
Largest Contentful Paint (LCP)	< 2.5s	Lighthouse
Cumulative Layout Shift (CLS)	< 0.1	Lighthouse

Métriques Fonctionnelles

• ✅ 10 User Stories principales implémentées
• ✅ 0 bug critique en production
• ✅ 100% des features Legacy reproduites (améliorées)
• ✅ Authentification OAuth fonctionnelle
• ✅ Temps réel opérationnel (stocks)
• ✅ Paiement Stripe intégré

Métriques Architecturales

• ✅ 6 microservices implémentés avec Clean Architecture
• ✅ 5+ design patterns appliqués
• ✅ SOLID respecté (0 violation)
• ✅ Event Bus fonctionnel (3+ événements)
• ✅ API Gateway / BFF implémenté
• ✅ 8+ documents livrables créés

---

⚠️ Risques & Mitigations

Risque	Probabilité	Impact	Mitigation
Complexité de Clean Architecture	Moyenne	Moyen	Suivre strictement les exemples, documentation détaillée
Supabase Realtime limitations	Faible	Moyen	Tester tôt, fallback polling si nécessaire
Stripe Test Mode bugs	Faible	Faible	Utiliser webhooks test, documentation Stripe
Performance Next.js SSR	Faible	Moyen	ISR + caching, monitoring Vercel
Délais serrés (5 semaines)	Élevée	Élevé	Priorisation stricte, US optionnelles clairement identifiées
Over-engineering	Moyenne	Moyen	YAGNI, focus MVP, complexité justifiée

---

🚀 Prochaines Étapes

Semaine 5 ✅ (Terminée - 2 Novembre 2025)

1. ✅ Créer structure apps/modern-app/
2. ✅ Initialiser Next.js 14 avec App Router
3. ✅ Setup TypeScript strict + ESLint + Prettier
4. ✅ Installer Tailwind CSS + shadcn/ui
5. ✅ Créer structure microservices (services/)
6. ✅ Setup Supabase projet + tables de base
7. ✅ Créer les 4 documents livrables principaux
8. ✅ Configuration CI/CD (GitHub Actions + Vercel)
9. ✅ Migrations database appliquées (entrepots, categories, tools)
10. ✅ TypeScript types générés depuis Supabase

Voir détails : Semaine 5 - Setup & Structure

Semaine 6 (En cours)

1. 🔲 Implémenter Auth Service (Clean Architecture)
2. 🔲 Configurer Supabase Auth (Email + OAuth Google)
3. 🔲 Créer pages d'authentification (Login/Register)
4. 🔲 Middleware de protection des routes
5. 🔲 Tests unitaires Auth Service (> 80% coverage)

Voir détails : Semaine 6 - Auth Service

---

Maintenu par : Équipe Architecture BricoLoc
Dernière mise à jour : 2 Novembre 2025
Prochaine révision : Fin Semaine 6