lib.rs

Description

Fichier racine de la bibliothèque koprogo_api. Ce fichier déclare les modules publics qui composent l’architecture hexagonale de l’application. Il sert de point d’entrée pour l’exposition des modules à l’extérieur de la crate.

Responsabilités

Déclaration des modules publics - Exposition des trois couches de l’architecture hexagonale - Organisation de la structure du projet
Encapsulation - Contrôle de la visibilité des modules - Permet aux autres fichiers d’importer via koprogo_api::*

Modules

application

Module: pub mod application

Description:

Couche application de l’architecture hexagonale. Contient la logique métier de l’application organisée selon le pattern Use Cases.

Contenu:

use_cases/ - Cas d’usage métier (AuthUseCases, BuildingUseCases, etc.)
dto/ - Data Transfer Objects pour les échanges de données
ports/ - Interfaces (traits) pour les repositories

Rôle:

Cette couche orchestre les opérations métier en utilisant les entités du domaine et les repositories de l’infrastructure. Elle est indépendante de la base de données et du framework web.

domain

Module: pub mod domain

Description:

Couche domaine de l’architecture hexagonale. Contient les entités métier et la logique métier pure.

Contenu:

entities/ - Entités métier (User, Building, Unit, Owner, Expense, etc.)
services/ - Services de domaine (ExpenseCalculator)

Rôle:

Cette couche représente le cœur métier de l’application. Elle est complètement indépendante des frameworks, de la base de données et des protocoles de communication. Les entités contiennent leur propre validation métier.

infrastructure

Module: pub mod infrastructure

Description:

Couche infrastructure de l’architecture hexagonale. Contient les implémentations techniques des adaptateurs externes.

Contenu:

database/ - Implémentation des repositories PostgreSQL avec SQLx
web/ - Configuration Actix-web, handlers HTTP, routes, middleware

Rôle:

Cette couche implémente les détails techniques de l’application:

Accès à la base de données PostgreSQL
Exposition des endpoints HTTP REST
Sérialisation/désérialisation JSON
Gestion des erreurs HTTP

Architecture hexagonale

Le fichier organise l’application selon le pattern Hexagonal Architecture (Ports & Adapters):

┌──────────────────────────────────────────────────────────────┐
│                         lib.rs                               │
│                   (Module Declarations)                      │
└──────────────────────────────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               ▼               ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│   DOMAIN    │  │ APPLICATION │  │INFRASTRUCTURE│
│  (Entities) │  │(Use Cases)  │  │  (Adapters) │
└─────────────┘  └─────────────┘  └─────────────┘
     Core              │                  │
    Métier        Orchestration    Implémentation
                                      Technique

Flux de dépendances

Les dépendances suivent la règle de l’architecture hexagonale:

Infrastructure ──> Application ──> Domain
     (Web)          (Use Cases)   (Entities)
     (DB)

❌ Domain ne dépend de personne
❌ Application dépend uniquement de Domain
❌ Infrastructure dépend de Application et Domain

Principe: Les détails techniques (web, DB) dépendent du métier, jamais l’inverse.

Utilisation

Dans main.rs:

use koprogo_api::application::use_cases::*;
use koprogo_api::infrastructure::database::*;
use koprogo_api::infrastructure::web::{configure_routes, AppState};

Dans les tests:

use koprogo_api::domain::entities::Building;
use koprogo_api::application::dto::BuildingDto;

Dans d’autres crates:

// Cargo.toml
[dependencies]
koprogo_api = { path = "../backend" }

// Dans le code
use koprogo_api::domain::entities::User;

Structure complète du projet

src/
├── lib.rs                    (ce fichier)
├── main.rs                   (point d'entrée serveur)
├── config.rs                 (configuration)
├── db.rs                     (utilitaires DB)
│
├── domain/
│   ├── mod.rs
│   ├── entities/
│   │   ├── user.rs
│   │   ├── organization.rs
│   │   ├── building.rs
│   │   ├── unit.rs
│   │   ├── owner.rs
│   │   ├── expense.rs
│   │   ├── meeting.rs
│   │   └── document.rs
│   └── services/
│       └── expense_calculator.rs
│
├── application/
│   ├── mod.rs
│   ├── dto/
│   │   ├── auth_dto.rs
│   │   ├── building_dto.rs
│   │   ├── unit_dto.rs
│   │   ├── owner_dto.rs
│   │   └── expense_dto.rs
│   ├── ports/
│   │   ├── user_repository.rs
│   │   ├── organization_repository.rs
│   │   ├── building_repository.rs
│   │   ├── unit_repository.rs
│   │   ├── owner_repository.rs
│   │   ├── expense_repository.rs
│   │   ├── meeting_repository.rs
│   │   └── document_repository.rs
│   └── use_cases/
│       ├── auth_use_cases.rs
│       ├── building_use_cases.rs
│       ├── unit_use_cases.rs
│       ├── owner_use_cases.rs
│       └── expense_use_cases.rs
│
└── infrastructure/
    ├── mod.rs
    ├── database/
    │   ├── mod.rs
    │   ├── pool.rs
    │   ├── seed.rs
    │   └── repositories/
    │       ├── user_repository_impl.rs
    │       ├── organization_repository_impl.rs
    │       ├── building_repository_impl.rs
    │       ├── unit_repository_impl.rs
    │       ├── owner_repository_impl.rs
    │       ├── expense_repository_impl.rs
    │       ├── meeting_repository_impl.rs
    │       └── document_repository_impl.rs
    └── web/
        ├── mod.rs
        ├── app_state.rs
        ├── routes.rs
        └── handlers/
            ├── auth_handlers.rs
            ├── seed_handlers.rs
            ├── building_handlers.rs
            ├── unit_handlers.rs
            ├── owner_handlers.rs
            ├── expense_handlers.rs
            └── health.rs

Avantages de cette architecture

Testabilité - Chaque couche peut être testée indépendamment - Mock des repositories facilité par les traits (ports)
Maintenabilité - Séparation claire des responsabilités - Changement de base de données sans toucher au métier
Évolutivité - Ajout de nouveaux use cases sans modifier l’infrastructure - Ajout de nouveaux adapters (GraphQL, gRPC) facilement
Indépendance des frameworks - Logique métier isolée d’Actix-web et SQLx - Migration vers un autre framework facilitée

Références

Clean Architecture (Robert C. Martin)
Hexagonal Architecture (Alistair Cockburn)
Domain-Driven Design (Eric Evans)

Fichiers associés

backend/src/main.rs - Point d’entrée principal
backend/src/domain/mod.rs - Module domaine
backend/src/application/mod.rs - Module application
backend/src/infrastructure/mod.rs - Module infrastructure