📙 Proposition : Adoption des Principes de la Clean Architecture pour un Développement Durable

0. Resources

clean architecture en frontend: https://github.com/david-ouatedem/clean-frontend-template

clean architecture en backend: https://github.com/david-ouatedem/clean-backend-template

comprendre la clean architecture:

1. Contexte

À mesure que notre application évolue en fonctionnalités et en complexité, nous commençons à faire face à des défis courants de mise à l’échelle(scaling) :

L’ajout de nouvelles fonctionnalités nécessite souvent de modifier plusieurs couches de code.
De petites mises à jour introduisent parfois des bugs inattendus dans des zones non liées.
L’intégration de nouveaux développeurs prend du temps car la logique métier et les détails du framework sont étroitement couplés.
Le changement ou la mise à niveau des technologies (par exemple, ORM, APIs) semble risqué et chronophage.

Ce sont des symptômes naturels d’un couplage étroit entre notre logique métier et le framework/infrastructure.

Pour résoudre cela, je propose que nous commencions à adopter les principes de la Clean Architecture dans les nouveaux projets.

2. Ce que signifie la Clean Architecture (en termes pratiques)

La Clean Architecture est une façon de structurer notre code de sorte que :

La logique métier (nos règles et cas d’usage réels) est indépendante des frameworks, bases de données ou APIs.
Les frameworks et outils deviennent des détails remplaçables — et non des parties centrales de notre logique.
Chaque fonctionnalité ou module a une structure cohérente et prévisible, facilitant son extension et ses tests.

En d’autres termes : la Clean Architecture sépare ce que fait l’application de la façon dont elle le fait.

3. Principaux Avantages pour Notre Équipe et Notre Produit

Défi	Comment la Clean Architecture aide
Livraison lente des fonctionnalités	Chaque fonctionnalité est isolée dans une seule classe “cas d’usage”. Les changements deviennent plus rapides et plus sûrs.
Régressions fréquentes	Les couches sont indépendantes. L’impact d’un changement est prévisible et contenu.
Intégration difficile	Structure cohérente : contrôleurs → cas d’usage → dépôts. Modèle mental plus facile pour les nouveaux contributeurs.
Verrouillage technologique	La logique centrale est indépendante du framework. L’infrastructure peut changer sans réécrire les règles métier.
Code difficile à tester	Les cas d’usage purs peuvent être testés unitairement instantanément sans dépendances.

4. À Quoi Cela Ressemble en Pratique

Au lieu de mettre toute la logique dans un service NestJS ou React, nous la séparons en couches :

src/
├── domain/          # Modèles métier de base (entités, règles)
├── application/     # Cas d'usage (logique métier pure, pas de framework)
├── infrastructure/  # BD, API, adaptateurs (NestJS, Prisma, etc.)
└── interface/       # Contrôleurs, résolveurs, DTOs (côté NestJS)

Exemple :

application/use-cases/register-user.usecase.ts

export class RegisterUserUseCase {
  constructor(private readonly usersRepo: UsersRepository) {}

  async execute(input: RegisterUserDto) {
    const user = new User(input.name, input.email);
    await this.usersRepo.save(user);
  }
}

interface/http/user.controller.ts

@Controller("users")
export class UserController {
  constructor(private readonly registerUser: RegisterUserUseCase) {}

  @Post()
  async register(@Body() dto: RegisterUserDto) {
    await this.registerUser.execute(dto);
  }
}

5. Comment Nous Pouvons l’Adopter

Nous n’avons pas besoin d’une réécriture complète des modules existants.

Au lieu de cela, nous pouvons introduire la Clean Architecture graduellement, en commençant par de nouvelles fonctionnalités ou des refactorisations ou le faire sur des nouveaux projets.

Adoption sur les Nouveaux Projets

Pour les nouveaux projets, nous recommandons d’intégrer la Clean Architecture dès le départ :

Étape 1 : Initialiser le projet avec une structure claire (domain, application, infrastructure, interface) dans chaque modules dans src/modules.

Étape 2 : Définir les premières fonctionnalités du projet (par exemple, authentification, gestion des utilisateurs) en suivant systématiquement ce modèle architectural.

Étape 3 : Établir des conventions et des templates de code pour garantir la cohérence dès le début.

Étape 4 : Former l’équipe sur ces principes avant le démarrage du développement. Adoption sur les Projets Existants

Pour les projets déjà en cours, une approche progressive est préférable :

Étape 1 : Créer la nouvelle structure (domain, application, infrastructure, interface) pour chaque nouveau module dans src/modules en parallèle du code existant.

Étape 2 : Implémenter les nouvelles fonctionnalités en suivant l’Architecture Propre.

Étape 3 : Refactoriser progressivement les modules critiques ou fréquemment modifiés.

Étape 4 : Évaluer les résultats — clarté, testabilité et vitesse de développement.

Si les résultats sont positifs, nous étendons le modèle à d’autres parties de l’application au fil du temps.

6. Résultats Attendus

En appliquant la Clean Architecture, nous pouvons nous attendre à :

Une livraison de fonctionnalités plus rapide avec moins de conflits de fusion
Des effets secondaires réduits lors de la mise à jour des fonctionnalités existantes
Une intégration plus simple pour les nouveaux développeurs
Une flexibilité pour faire évoluer notre pile technologique en toute sécurité
Une plus grande confiance dans les déploiements grâce à des tests isolés

7. Résumé de la Proposition

Objectif : Implémenter la Clean Architecture dans les nouveaux projets et potentiellement l’adopter dans les nouveaux modules des projets existants

But : Améliorer la maintenabilité, la cohérence et la vitesse de développement

Approche : Commencer avec un nouveau projet

Avantages : Itération plus rapide, changements plus sûrs, intégration plus facile, flexibilité à long terme

8. Prochaine Étape

Si l’équipe est d’accord, nous pouvons :

Choisir un projet à venir.
L’implémenter en utilisant la Clean Architecture.
Examiner les résultats ensemble avant de décider de l’appliquer plus largement.

Préparé par :
Ouatedem David
Ingénieur Logiciel