Project Structure Guide - Jipmaa/WE4B GitHub Wiki

Ce guide explique l'organisation et les conventions utilisées dans notre application web full-stack construite avec Angular (frontend) et Express.js (backend).

📁 Structure Complète du Projet

project-root/
├── client/                          # Application frontend Angular
│   ├── public/                      # Ressources statiques (favicon, images, etc.)
│   └── src/
│       └── app/                     # Application Angular principale (alias: @/)
│           ├── core/                # Services singleton et fonctionnalités à l'échelle de l'application
│           │   ├── guards/          # Logique de protection des routes
│           │   │   └── auth.guard.ts
│           │   ├── interceptors/    # Intercepteurs de requêtes/réponses HTTP
│           │   │   └── auth.interceptor.ts
│           │   ├── models/          # Interfaces/types TypeScript partagés
│           │   │   ├── _shared.models.ts
│           │   │   ├── auth.models.ts
│           │   │   └── course-unit.models.ts
│           │   └── services/        # Services singleton à l'échelle de l'application
│           │       ├── auth.service.ts
│           │       ├── course-unit.service.ts
│           │       └── api.service.ts
│           ├── features/            # Modules spécifiques aux fonctionnalités
│           │   ├── authentication/  # Exemple : Fonctionnalité d'authentification
│           │   │   ├── components/  # Composants spécifiques à cette fonctionnalité
│           │   │   │   ├── login/
│           │   │   │   │   ├── login.component.ts
│           │   │   │   │   ├── login.component.html
│           │   │   │   │   └── login.component.spec.ts
│           │   │   │   └── register/
│           │   │   │       ├── register.component.ts
│           │   │   │       ├── register.component.html
│           │   │   │       └── register.component.spec.ts
│           │   │   └── authentication.routes.ts
│           │   └── course-management/  # Exemple : Fonctionnalité de gestion de cours
│           │       ├── components/     # Composants spécifiques à la fonctionnalité
│           │       │   ├── course-list/
│           │       │   ├── course-detail/
│           │       │   └── course-form/
│           │       ├── models/         # Modèles spécifiques à la fonctionnalité (optionnel)
│           │       │   └── course-management.models.ts
│           │       ├── services/       # Services spécifiques à la fonctionnalité (optionnel)
│           │       │   └── course-management.service.ts
│           │       └── course-management.routes.ts
│           └── shared/              # Composants et utilitaires réutilisables
│               ├── components/      # Composants d'interface utilisateur réutilisables
│               │   ├── layout/      # Composants de mise en page de l'application
│               │   │   ├── header/
│               │   │   ├── footer/
│               │   │   └── sidebar/
│               │   └── ui/          # Éléments d'interface utilisateur de base réutilisables
│               │       ├── button/
│               │       ├── modal/
│               │       ├── table/
│               │       └── form/
│               ├── directives/      # Directives Angular personnalisées
│               ├── pipes/           # Pipes Angular personnalisés
│               ├── types/           # Types TypeScript partagés
│               └── utils/           # Fonctions utilitaires et helpers
└── server/                          # Application backend Express.js
    ├── src/
    │   ├── middleware/              # Fonctions middleware Express
    │   │   ├── auth-middleware.ts   # Middleware d'authentification
    │   │   ├── error-handler.ts     # Gestion globale des erreurs
    │   │   ├── not-found.ts         # Gestionnaire d'erreur 404
    │   │   ├── roles-middleware.ts  # Contrôle d'accès basé sur les rôles
    │   │   └── validate-request.ts  # Middleware de validation des requêtes
    │   ├── models/                  # Modèles de base de données Mongoose
    │   │   ├── course-unit.ts       # Modèle de données d'unité de cours
    │   │   ├── user.ts              # Modèle de données utilisateur
    │   │   └── enrollment.ts        # Modèle de données d'inscription
    │   ├── routes/                  # Définitions des routes Express
    │   │   ├── auth-routes.ts       # Points de terminaison d'authentification
    │   │   ├── course-unit-routes.ts # Points de terminaison CRUD d'unité de cours
    │   │   ├── setup-routes.ts      # Points de terminaison de configuration initiale
    │   │   └── user-routes.ts       # Points de terminaison de gestion des utilisateurs
    │   ├── utils/                   # Fonctions utilitaires et helpers
    │   │   ├── app-error.ts         # Classe d'erreur personnalisée
    │   │   ├── async-handler.ts     # Wrapper de gestion d'erreurs asynchrones
    │   │   └── database.ts          # Utilitaires de connexion à la base de données
    │   └── index.ts                 # Point d'entrée du serveur
    ├── .env                         # Variables d'environnement (non dans le contrôle de version)
    ├── .env.example                 # Modèle de variables d'environnement
    └── docker-compose.yml           # Configuration Docker pour le développement

🎯 Conventions de Nommage

Tous noms de fichiers et de variables doivent être en anglais.

Nommage des Fichiers

• snake-case pour tous les fichiers : auth-middleware.ts, course-unit.ts, user-routes.ts
• snake-case pour les composants Angular : course-list, user-profile, login-form
• Suffixes descriptifs pour les fichiers Angular : .service.ts, .component.ts, .guard.ts, .routes.ts

Conventions de Code

• camelCase pour les variables et fonctions : getUserById, courseUnits, isAuthenticated
• PascalCase pour les classes et interfaces : CourseUnit, AuthService, UserModel
• UPPER_SNAKE_CASE pour les constantes : API_BASE_URL, MAX_FILE_SIZE

📂 Organisation des Dossiers Expliquée

Structure Client (Angular)

core/ - Fondation de l'Application

Contient les services singleton et les fonctionnalités à l'échelle de l'application qui ne doivent être importées qu'une seule fois :

• guards/ : Protègent les routes (authentification, autorisation)
• interceptors/ : Gèrent les requêtes/réponses HTTP globalement
• models/ : Interfaces TypeScript partagées utilisées dans toute l'application
• services/ : Services globaux (communication API, authentification)

features/ - Modules de Logique Métier

Chaque fonctionnalité obtient son propre dossier contenant tout ce qui est lié à cette fonctionnalité spécifique :

• components/ : Composants d'interface utilisateur spécifiques à cette fonctionnalité
• models/ : Types/interfaces utilisés uniquement dans cette fonctionnalité
• services/ : Services de logique métier spécifiques à cette fonctionnalité
• routes/ : Configuration des routes pour cette fonctionnalité

shared/ - Éléments Réutilisables

Composants et utilitaires qui peuvent être utilisés dans plusieurs fonctionnalités :

• components/layout/ : Composants de mise en page à l'échelle de l'application (en-tête, pied de page, navigation)
• components/ui/ : Composants d'interface utilisateur génériques (boutons, modales, formulaires)
• directives/ : Directives Angular personnalisées
• pipes/ : Pipes de transformation de données personnalisés
• types/ : Types TypeScript communs
• utils/ : Fonctions d'aide et utilitaires

Structure Serveur (Express)

middleware/ - Traitement des Requêtes

Fonctions qui traitent les requêtes avant qu'elles n'atteignent les gestionnaires de routes :

• auth-middleware.ts : Valide les jetons d'authentification des utilisateurs
• error-handler.ts : Gestion centralisée des erreurs et formatage des réponses
• roles-middleware.ts : Vérifie les permissions des utilisateurs pour les ressources protégées
• validate-request.ts : Valide les données des requêtes entrantes

models/ - Couche de Données

Schémas Mongoose qui définissent la structure de la base de données et les règles métier :

• course-unit.ts : Modèle de données d'unité de cours et validation
• user.ts : Modèle de compte utilisateur avec champs d'authentification

routes/ - Points de Terminaison API

Modules de routeur Express qui définissent les points de terminaison API :

• auth-routes.ts : Points de terminaison de connexion, déconnexion, inscription
• course-unit-routes.ts : Opérations CRUD pour les unités de cours
• setup-routes.ts : Points de terminaison de configuration initiale de l'application

utils/ - Fonctions d'Aide

Fonctions utilitaires et classes utilisées dans tout le serveur :

• app-error.ts : Classe d'erreur personnalisée pour une gestion cohérente des erreurs
• async-handler.ts : Wrapper pour les gestionnaires de routes asynchrones

🔧 Conventions Spéciales

Alias de Chemin Angular

• Utilisez @/ comme alias pour src/app/ dans les imports
• Exemple : import { AuthService } from '@/core/services/auth.service'

Framework CSS

• Tailwind CSS est utilisé au lieu de fichiers CSS spécifiques aux composants
• Aucun fichier .css dans les dossiers de composants (les styles sont appliqués via les classes Tailwind)

Configuration d'Environnement du Serveur

• Développement : Utilisez le fichier .env pour la configuration locale
• Production : Variables d'environnement définies via la plateforme de déploiement
• Modèle : .env.example montre les variables d'environnement requises

📋 Meilleures Pratiques

Organisation des Fichiers

• Gardez les fichiers liés ensemble dans les dossiers de fonctionnalités
• Utilisez des noms de fichiers descriptifs qui indiquent leur objectif
• Séparez les préoccupations : modèles, services, composants dans leurs dossiers respectifs

Organisation des Imports

• Utilisez des imports absolus avec l'alias @/ pour une meilleure lisibilité
• Gardez les imports organisés et supprimez ceux qui ne sont pas utilisés

Structure des Composants

• Composants petits et ciblés qui font une chose bien
• Utilisez les dossiers de fonctionnalités pour regrouper les composants liés
• Les composants partagés vont dans shared/components/