Skip to main content
Cette page décrit l’architecture feature-based du frontend Châtaigne, conçue pour être modulaire, maintenable et évolutive avec Next.js 14.

​
Organisation Générale

Le frontend utilise une architecture feature-based plutôt que page-based, permettant une meilleure scalabilité et maintenabilité du code. 
src/
├── app/               # Next.js App Router (routing uniquement)
├── features/          # Modules métier autonomes
├── shared/            # Ressources partagées
├── styles/            # Styles globaux
└── config/            # Configuration

​
Stack Technique

Framework & Language

• Next.js 14 - Framework React avec App Router• TypeScript - Type safety et meilleure DX

State Management

• TanStack Query - Gestion du cache et des requêtes API• Zustand - State management léger pour l’état client

UI & Styling

• Tailwind CSS - Styling utility-first• shadcn/ui - Composants UI réutilisables

Validation & Forms

• Zod - Validation de schémas runtime• React Hook Form - Gestion des formulaires performante

​
Couches Principales

1

App Directory (Routing)

Gestion du routing uniquement :
  • Fichiers extrêmement légers
  • Import direct des vues depuis les features
  • Aucune logique métier
2

Features (Modules métier)

Modules autonomes et complets :
  • Views : Composition visuelle uniquement
  • Hooks : Toute la logique métier et TanStack Query
  • Services : Communication avec les APIs
  • Store : État client local (Zustand)
  • Components : Éléments UI spécifiques
3

Shared (Ressources partagées)

Éléments réutilisables :
  • Components : shadcn/ui et composants communs
  • Hooks : Hooks partagés et requêtes communes
  • Services : API client et services globaux
  • Store : État global de l’application
src/
├── app/                      # Next.js App Router
│   ├── (auth)/              # Route groups
│   │   ├── login/
│   │   │   └── page.tsx     # export default () => <LoginView />
│   │   └── register/
│   │       └── page.tsx
│   ├── dashboard/
│   │   └── page.tsx
│   └── layout.tsx
│
├── features/                 # Modules métier autonomes
│   ├── auth/
│   │   ├── components/      # Composants spécifiques à auth
│   │   │   ├── login-form.component.tsx
│   │   │   └── auth-guard.component.tsx
│   │   ├── views/          # Pages exportées par la feature
│   │   │   ├── login.view.tsx
│   │   │   └── register.view.tsx
│   │   ├── hooks/          # Logique métier et TanStack Query
│   │   │   ├── use-auth.hook.ts
│   │   │   └── use-auth-form.hook.ts
│   │   ├── services/       # Appels API
│   │   │   └── auth.service.ts
│   │   ├── store/          # État Zustand (UI uniquement)
│   │   │   └── auth.store.ts
│   │   ├── validations/    # Schémas Zod
│   │   │   └── auth.schema.ts
│   │   └── types/          # Types TypeScript
│   │       └── auth.type.ts
│   │
│   └── dashboard/
│       ├── components/
│       ├── views/
│       ├── hooks/
│       ├── services/
│       ├── store/
│       └── types/
│
├── shared/                  # Ressources partagées
│   ├── components/         # Composants réutilisables
│   │   ├── ui/            # shadcn/ui components
│   │   └── common/        # Composants métier partagés
│   ├── hooks/             # Hooks partagés
│   │   ├── queries/       # Hooks TanStack Query partagés
│   │   └── mutations/     # Mutations TanStack Query
│   ├── services/          # Services communs
│   │   └── api.client.ts
│   ├── store/             # État global
│   ├── utils/             # Utilitaires communs
│   └── types/             # Types globaux
│
├── styles/                 # Styles globaux
└── config/                # Configuration
    ├── query.config.ts    # Configuration TanStack Query
    └── env.config.ts

​
Conventions de Nommage

Nous utilisons des conventions strictes avec kebab-case et des suffixes spécifiques.

​
Fichiers

Tous les fichiers suivent le format kebab-case avec des suffixes spécifiques selon leur type :

Components & Views

• .component.tsx - Composants UI• .view.tsx - Pages/vues principales

Logique & Services

• .hook.ts - Hooks custom• .service.ts - Services API

État & Validation

• .store.ts - Stores Zustand• .schema.ts - Schémas Zod

Configuration

• .type.ts - Types TypeScript• .config.ts - Configuration

​
Exports TypeScript

  • PascalCase pour les interfaces/types
  • camelCase pour les schémas Zod

​
Gestion d’État Hybride

Principe fondamental : Séparation claire entre état serveur et état client.
Le frontend utilise une approche hybride pour la gestion d’état :
  • TanStack Query : Pour tout l’état serveur (data fetching, cache, synchronisation)
  • Zustand : Pour l’état client uniquement (UI state, préférences utilisateur)

​
Points d’Attention

Séparation des responsabilités

• Views : Composition et orchestration des composants• Hooks : Logique métier et gestion d’état• Services : Communication avec les APIs externes• Components : Composants présentationnels réutilisables

État hybride

• TanStack Query pour l’état serveur• Zustand pour l’état client uniquement• Jamais de duplication entre les deux

Feature autonome

• Chaque feature est indépendante• Minimisation des dépendances inter-features• Facilite le code splitting

Type safety

• TypeScript partout• Validation avec Zod• Inférence de types maximale
Cette architecture feature-based permet une séparation claire des responsabilités, une meilleure performance grâce au cache intelligent de TanStack Query, et une scalabilité optimale pour l’évolution du projet.