ansiblenginx/app/bricolociaac/docs/architecture/ADR/002-framework-frontend.md

# ADR-002 : Next.js 14 comme Framework Frontend

**Statut** : ✅ Accepté  
**Date** : Octobre 2025  
**Décideurs** : Équipe Architecture  
**Tags** : `frontend`, `framework`, `react`

---

## Contexte

L'application moderne nécessite un **framework React** performant avec :
- Support **TypeScript** natif
- **Server-Side Rendering (SSR)** pour SEO
- **API Routes** intégrées (Backend For Frontend)
- Performance optimale
- DX (Developer Experience) excellente

### Options considérées
1. **Next.js 14** (App Router)
2. **Remix**
3. **Vite + React Router**
4. **Create React App** (CRA)

---

## Décision

✅ **Nous adoptons Next.js 14 avec App Router**

---

## Justification

### Pourquoi Next.js ?

#### 1. **Écosystème Mature** 🌟
- Framework le plus populaire React (utilisé par Vercel, Netflix, TikTok, etc.)
- Communauté énorme
- Documentation excellente
- Ressources d'apprentissage abondantes

#### 2. **Performance Exceptionnelle** ⚡
- **SSR/SSG** natifs (SEO optimal)
- **Streaming** (React 18 Server Components)
- **Image Optimization** automatique (`next/image`)
- **Code Splitting** automatique
- **Lazy Loading** built-in

#### 3. **App Router (Next.js 14)** 🚀
- **Server Components** par défaut (moins de JS client)
- **Nested Layouts** (partage de UI)
- **Loading UI** et **Error Boundaries** intégrés
- **Parallel Routes** et **Intercepting Routes**
- Routing basé sur le système de fichiers (convention over configuration)

#### 4. **Backend Intégré (BFF Pattern)** 🔧
- **API Routes** (`app/api/`)
- Parfait pour notre **API Gateway / BFF**
- Déploiement unifié (frontend + backend)
- Middleware pour auth, logging, etc.

#### 5. **TypeScript First** 📘
- Support TypeScript natif
- Typage automatique des routes
- Autocomplétion des imports

#### 6. **Déploiement Simplifié** ☁️
- **Vercel** (hébergement optimisé)
- Déploiement en 1 clic
- Preview deployments automatiques
- Edge Functions disponibles

#### 7. **Écosystème Intégré** 🛠️
- Compatible avec **shadcn/ui**
- Intégration **Tailwind CSS** excellente
- Support **React Query**, **Zustand**, etc.

---

## Comparaison des Alternatives

| Critère | Next.js 14 | Remix | Vite + RR | CRA |
|---------|------------|-------|-----------|-----|
| **SSR/SSG** | ✅✅✅ Natif | ✅✅ Natif | ⚠️ Manuel | ❌ CSR only |
| **API Routes** | ✅ Oui | ✅ Oui | ❌ Non | ❌ Non |
| **Performance** | ✅✅✅ | ✅✅ | ✅✅ | ⚠️ |
| **DX** | ✅✅✅ | ✅✅ | ✅✅ | ⚠️ |
| **Communauté** | ✅✅✅ Énorme | ✅ Croissante | ✅✅ | ⚠️ Déprécié |
| **Déploiement** | ✅✅✅ Vercel | ✅ Fly.io | ⚠️ Manuel | ⚠️ |
| **Courbe apprentissage** | ⚠️ Moyenne | ⚠️ Moyenne | ✅ Faible | ✅ Faible |
| **Popularité 2025** | ✅✅✅ | ✅ | ✅✅ | ❌ |

---

## App Router vs Pages Router

Nous choisissons **App Router** (Next.js 13+) :

| Feature | Pages Router | App Router |
|---------|--------------|------------|
| **Server Components** | ❌ Non | ✅ Oui |
| **Nested Layouts** | ⚠️ Layout HOC | ✅ Natif |
| **Streaming** | ❌ Non | ✅ Oui |
| **Loading States** | ⚠️ Manuel | ✅ Natif |
| **Error Handling** | ⚠️ _error.js | ✅ error.tsx |
| **Parallel Routes** | ❌ Non | ✅ Oui |
| **Metadata API** | ⚠️ Head | ✅ Metadata object |
| **Futur** | ⚠️ Legacy | ✅ Recommandé |

**Conclusion** : App Router est le futur de Next.js

---

## Architecture avec Next.js

### Structure

```
apps/modern-app/
├── src/
│   ├── app/                    # App Router
│   │   ├── (auth)/            # Route group (auth pages)
│   │   ├── (main)/            # Route group (main app)
│   │   ├── api/               # API Routes (BFF)
│   │   ├── layout.tsx         # Root layout
│   │   └── page.tsx           # Home page
│   │
│   ├── components/            # React Components
│   ├── services/              # Microservices logic
│   └── lib/                   # Utilities
```

### BFF Pattern avec API Routes

```typescript
// app/api/reservations/route.ts
export async function POST(request: Request) {
  // API Gateway logic
  const data = await request.json()
  
  // Orchestrate microservices
  const availability = await inventoryService.check(data)
  const reservation = await reservationService.create(data)
  const payment = await paymentService.createIntent(reservation)
  
  return Response.json({ reservation, payment })
}
```

---

## Conséquences

### ✅ Avantages

1. **Performance** : Lighthouse scores > 95
2. **SEO** : SSR natif
3. **DX** : Hot reload, Fast Refresh
4. **BFF** : API Routes intégrées
5. **Déploiement** : Vercel en 1 clic
6. **Maintenance** : Framework mainstream
7. **Portfolio** : Technologie recherchée

### ⚠️ Inconvénients

1. **Complexité initiale** : App Router = courbe d'apprentissage
2. **Magie** : Conventions à connaître (Server Components, etc.)
3. **Vendor lock-in** : Optimisé pour Vercel (mais pas obligatoire)

### 🛠️ Mitigations

- Formation App Router (documentation Next.js)
- Exemples de code commentés
- Isolation de la logique métier (services indépendants)

---

## Alternatives Rejetées

### ❌ Remix

**Avantages** :
- Excellente gestion des forms
- Nested routes puissants
- Philosophie web-native

**Raisons du rejet** :
- Communauté plus petite
- Moins de ressources/exemples
- Déploiement moins simple que Vercel
- Moins connu = moins impressionnant pour portfolio

### ❌ Vite + React Router

**Avantages** :
- Build ultra-rapide (Vite)
- Flexibilité maximale
- Lightweight

**Raisons du rejet** :
- Pas d'API Routes intégrées (besoin backend séparé)
- SSR manuel à configurer
- Moins de conventions (plus de décisions)
- Pas de BFF pattern natif

### ❌ Create React App (CRA)

**Raisons du rejet** :
- **Déprécié officiellement** par React
- CSR only (pas de SSR)
- Performance médiocre
- Pas d'API Routes
- Pas adapté 2025

---

## Références

- [Next.js 14 Documentation](https://nextjs.org/docs)
- [App Router vs Pages Router](https://nextjs.org/docs/app)
- [Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components)
- [Vercel Deployment](https://vercel.com/docs)

---

## Validations

- [x] POC App Router réalisé
- [x] Tests performance (Lighthouse)
- [x] Compatibilité avec Supabase validée
- [x] shadcn/ui compatible ✅

---

**Prochaine révision** : Si Next.js 15 sort avec changements majeurs