Architecture Next.js pour SaaS : le guide domain-driven

Le problème des architectures classiques

La plupart des projets Next.js finissent avec un dossier components/ de 50 fichiers, un dossier utils/ fourre-tout et des API routes qui mélangent validation, auth et logique métier. Ça fonctionne au début, mais ça ne scale pas.

L'approche domain-driven

Au lieu d'organiser par type technique (components, hooks, utils), j'organise par domaine métier :

src/domains/
├── projects/
│   ├── projects.schemas.ts    # Validation Zod
│   ├── projects.services.ts   # Requêtes Prisma pures
│   ├── projects.actions.ts    # Server Actions
│   └── components/            # UI spécifique
├── articles/
│   ├── articles.schemas.ts
│   ├── articles.services.ts
│   ├── articles.actions.ts
│   └── components/
└── auth/
    └── components/

Les 3 couches essentielles

1. Schemas (validation)

Un fichier Zod par domaine, partagé entre client (React Hook Form) et serveur (Server Actions). Single source of truth pour la validation.

2. Services (données)

Des fonctions pures qui appellent Prisma. Pas d'auth, pas de revalidation, juste des requêtes. Faciles à tester, faciles à réutiliser.

3. Actions (orchestration)

Les Server Actions orchestrent tout : vérification auth → validation Zod → appel service → revalidatePath. C'est le seul endroit où ces concerns se rencontrent.

Data flow

Le pattern est simple et prévisible :

• Lecture : Server Component → Service → Prisma → HTML statique
• Écriture : Client form → Server Action → Service → Prisma → revalidatePath

Zéro API route nécessaire pour le CRUD. Les Server Actions remplacent élégamment les endpoints REST classiques.

Pourquoi ça marche

Après 7 SaaS avec cette architecture :

• Je retrouve n'importe quel code en 10 secondes
• Ajouter un nouveau domaine prend 15 minutes (avec un skill Claude Code)
• Les bugs sont isolés : un problème de validation ne casse pas la couche données
• Le onboarding de nouveaux devs est rapide, la structure est auto-documentée