Documentation Technique Koprogo

Introduction 

Koprogo est une plateforme SaaS de gestion de copropriété développée avec une stack moderne:

Backend: Rust avec Actix-web et PostgreSQL
Frontend: Astro + Svelte en mode PWA
Architecture: Hexagonale (Ports & Adapters)
Multi-tenancy: Support organisationnel complet
Authentification: JWT avec rôles hiérarchiques

Vue d’ensemble du projet 

Structure générale 

koprogo/
├── backend/           # API Rust/Actix-web
│   ├── src/
│   │   ├── main.rs           # Point d'entrée serveur
│   │   ├── lib.rs            # Modules publics
│   │   ├── domain/           # Entités et logique métier
│   │   ├── application/      # Use cases et DTOs
│   │   └── infrastructure/   # Adapteurs (DB, Web)
│   ├── migrations/    # Migrations SQL
│   ├── tests/         # Tests BDD et E2E
│   └── benches/       # Tests de charge
│
├── frontend/          # Application Astro/Svelte
│   ├── src/
│   │   ├── pages/           # Pages Astro (routes)
│   │   ├── components/      # Composants Svelte
│   │   ├── lib/             # Utilitaires et stores
│   │   └── layouts/         # Layouts Astro
│   └── tests/e2e/    # Tests E2E Playwright
│
├── docs/             # Documentation (ce dossier)
├── docker-compose.yml
└── Makefile

Stack technique 

Backend 

Technologie	Utilisation
Rust (edition 2021, nightly)	Langage backend avec performance et sécurité
Actix-web 4.11	Framework web asynchrone haute performance
SQLx 0.8.6	Client PostgreSQL async avec migrations et macros
PostgreSQL 15	Base de données relationnelle
bcrypt 0.15	Hachage de mots de passe (cost 12)
jsonwebtoken 9.3	Authentification JWT
uuid 1.11	Identifiants uniques (v4)
chrono 0.4	Gestion des dates/timestamps
validator 0.18	Validation déclarative
serde 1.0	Sérialisation/désérialisation JSON

Frontend 

Technologie	Utilisation
Astro 5.x	Framework SSR/SSG pour pages et routing
Svelte 5.x	Composants interactifs réactifs
TypeScript 5.x	Typage statique
Vite 6.x	Build tool et dev server
@vite-pwa/astro	Support Progressive Web App
Workbox	Service Worker et stratégies de cache
IndexedDB	Base de données locale pour mode offline
Playwright	Tests E2E avec vidéos

DevOps 

Outil	Utilisation
Docker / docker-compose	Conteneurisation et orchestration
GitHub Actions	CI/CD avec workflows automatisés
Make	Commandes de développement
SQLx CLI	Gestion des migrations et query cache

Architecture Hexagonale 

Principes 

L’application backend suit l’architecture hexagonale (Ports & Adapters):

┌─────────────────────────────────────────────────────────────┐
│                    INFRASTRUCTURE                           │
│                                                             │
│   ┌──────────────┐                      ┌──────────────┐   │
│   │     Web      │                      │   Database   │   │
│   │  (Actix-web) │                      │  (PostgreSQL)│   │
│   │   Handlers   │                      │ Repositories │   │
│   └──────┬───────┘                      └───────┬──────┘   │
│          │                                      │          │
└──────────┼──────────────────────────────────────┼──────────┘
           │                                      │
           ▼                                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    APPLICATION                              │
│                                                             │
│   ┌──────────────┐        ┌──────────────┐                 │
│   │  Use Cases   │◄───────┤     DTOs     │                 │
│   │              │        │              │                 │
│   │ • AuthUseCases        │ • LoginRequest                 │
│   │ • BuildingUseCases    │ • BuildingDto                  │
│   │ • ...                 │ • ...                          │
│   └──────┬───────┘        └──────────────┘                 │
│          │                                                  │
│          │ utilise                                          │
│          ▼                                                  │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│                       DOMAIN                                │
│                                                             │
│   ┌──────────────┐        ┌──────────────┐                 │
│   │   Entities   │        │   Services   │                 │
│   │              │        │              │                 │
│   │ • User               │ • ExpenseCalculator             │
│   │ • Building           │                                 │
│   │ • Unit               │                                 │
│   │ • Owner              │                                 │
│   │ • Expense            │                                 │
│   └──────────────┘        └──────────────┘                 │
│                                                             │
│   📌 Cœur métier - Indépendant des frameworks              │
└─────────────────────────────────────────────────────────────┘

Flux de dépendances 

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

✅ Domain ne dépend de personne (pur métier)
✅ Application ne dépend que de Domain
✅ Infrastructure dépend de Application et Domain

Avantages 

Testabilité: Chaque couche testable indépendamment
Maintenabilité: Séparation claire des responsabilités
Évolutivité: Changement de framework/DB sans toucher au métier
Business-centric: La logique métier est au centre

Documentation Backend 

Point d’entrée 

Couche Domaine 

Entités métier 

Services de domaine 

Couche Application 

Use Cases 

Les use cases orchestrent la logique métier:

auth_use_cases.rs - Authentification, login, register
building_use_cases.rs - CRUD immeubles
unit_use_cases.rs - CRUD lots
owner_use_cases.rs - CRUD propriétaires
expense_use_cases.rs - CRUD charges

DTOs 

Data Transfer Objects pour les échanges API:

auth_dto.rs - LoginRequest, RegisterRequest, LoginResponse, Claims
building_dto.rs - BuildingDto, CreateBuildingRequest
unit_dto.rs - UnitDto, CreateUnitRequest
owner_dto.rs - OwnerDto, CreateOwnerRequest
expense_dto.rs - ExpenseDto, CreateExpenseRequest

Ports (Interfaces)

Traits définissant les contrats pour les repositories:

user_repository.rs
organization_repository.rs
building_repository.rs
unit_repository.rs
owner_repository.rs
expense_repository.rs
meeting_repository.rs
document_repository.rs

Couche Infrastructure 

Base de données 

infrastructure/database/
├── mod.rs                    # Exports publics
├── pool.rs                   # Pool de connexions SQLx
├── seed.rs                   # Seeding de données (SuperAdmin, demo)
└── 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 (API REST)

infrastructure/web/
├── mod.rs                    # Exports publics
├── app_state.rs              # État partagé de l'application
├── routes.rs                 # Configuration des routes
└── handlers/
    ├── auth_handlers.rs      # POST /api/v1/auth/login, /register, GET /me
    ├── seed_handlers.rs      # POST /api/v1/seed/demo, /clear
    ├── building_handlers.rs  # CRUD /api/v1/buildings
    ├── unit_handlers.rs      # CRUD /api/v1/units
    ├── owner_handlers.rs     # CRUD /api/v1/owners
    ├── expense_handlers.rs   # CRUD /api/v1/expenses
    └── health.rs             # GET /health

Migrations SQL 

Les migrations sont gérées par SQLx:

backend/migrations/
├── 20240101_create_users.sql
├── 20240102_create_organizations.sql
├── 20240103_create_buildings.sql
├── 20240104_create_units.sql
├── 20240105_create_owners.sql
├── 20240106_create_expenses.sql
└── ...

Exécuter les migrations:

cd backend
sqlx migrate run

Documentation Frontend 

Structure 

frontend/src/
├── pages/                  # Routes Astro (SSR/SSG)
│   ├── index.astro        # Landing page
│   ├── login.astro        # Page de connexion
│   ├── admin/
│   │   └── index.astro    # Dashboard SuperAdmin
│   ├── syndic/
│   │   └── index.astro    # Dashboard Syndic
│   ├── accountant/
│   │   └── index.astro    # Dashboard Comptable
│   ├── owner/
│   │   └── index.astro    # Dashboard Copropriétaire
│   └── buildings/
│       └── index.astro    # Liste des immeubles
│
├── components/             # Composants Svelte
│   ├── LoginForm.svelte
│   ├── Navigation.svelte
│   ├── SyncStatus.svelte
│   ├── BuildingList.svelte
│   └── dashboards/
│       ├── AdminDashboard.svelte
│       ├── SyndicDashboard.svelte
│       ├── AccountantDashboard.svelte
│       └── OwnerDashboard.svelte
│
├── lib/                    # Utilitaires et configuration
│   ├── config.ts          # Configuration API centralisée
│   ├── types.ts           # Types TypeScript
│   ├── db.ts              # Wrapper IndexedDB
│   └── sync.ts            # Service de synchronisation
│
├── stores/                 # Stores Svelte
│   └── auth.ts            # Store d'authentification
│
└── layouts/
    └── Layout.astro       # Layout principal

Fonctionnalités clés 

PWA (Progressive Web App)

Service Worker avec Workbox
Manifest PWA pour installation
Mode offline avec IndexedDB
Synchronisation bidirectionnelle

Authentification 

JWT avec refresh token
Persistance localStorage + IndexedDB
Redirections selon rôle
Middleware de protection des routes

Multi-rôles 

SuperAdmin: accès plateforme complet
Syndic: gestion complète immeubles
Accountant: accès finances
Owner: consultation limitée

Tests E2E 

Framework: Playwright avec enregistrement vidéo

frontend/tests/e2e/
├── config.ts              # Configuration des tests
├── auth.spec.ts           # Tests d'authentification (8 tests)
├── dashboards.spec.ts     # Tests des dashboards (8 tests)
└── pwa-offline.spec.ts    # Tests PWA/offline (8 tests)

Total: 24 tests E2E

Exécuter les tests:

cd frontend
npm run test:e2e         # Mode headless avec vidéos
npm run test:e2e:ui      # Mode UI interactif
npm run test:e2e:debug   # Mode debug pas à pas

API REST 

Authentification 

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123",
  "first_name": "John",
  "last_name": "Doe",
  "role": "syndic"
}

Response 201:
{
  "token": "eyJ...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "syndic"
  }
}

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response 200:
{
  "token": "eyJ...",
  "user": { /* ... */ }
}

GET /api/v1/auth/me
Authorization: Bearer eyJ...

Response 200:
{
  "id": "uuid",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "role": "syndic"
}

Immeubles 

GET /api/v1/buildings
Authorization: Bearer eyJ...

Response 200:
[
  {
    "id": "uuid",
    "name": "Résidence Les Jardins",
    "address": "123 Rue de la Paix",
    "city": "Paris",
    "postal_code": "75001",
    "country": "France",
    "total_units": 50
  }
]

Seeding 

POST /api/v1/seed/demo
Authorization: Bearer eyJ... (SuperAdmin)

Response 200:
{
  "message": "Demo data created successfully",
  "users": [/* credentials */]
}

POST /api/v1/seed/clear
Authorization: Bearer eyJ... (SuperAdmin)

Response 200:
{
  "message": "Demo data cleared successfully"
}

Guides de développement 

Installation 

# Cloner le projet
git clone https://github.com/your-org/koprogo.git
cd koprogo

# Installation complète
make setup

# Démarrer les services
make dev            # Backend seul
make dev-frontend   # Frontend seul (autre terminal)
make dev-all        # Tout en Docker

Commandes Make 

make help           # Affiche toutes les commandes disponibles
make setup          # Installation complète
make dev            # Démarre backend
make dev-frontend   # Démarre frontend
make dev-all        # Démarre tout avec Docker
make test           # Run all tests
make test-e2e       # Tests E2E avec vidéos
make clean          # Nettoyage

Workflow Git 

Créer une branche feature:
```
git checkout -b feature/my-feature
```

Développer et committer:

git add .
git commit -m "feat: Add my feature"

Pousser et créer PR:

git push origin feature/my-feature
gh pr create

CI/CD 

GitHub Actions avec 3 workflows:

Backend CI (.github/workflows/backend-ci.yml) - Tests unitaires - Tests BDD - Clippy (linter) - Format check
Frontend CI (.github/workflows/frontend-ci.yml) - Tests E2E avec vidéos - Build production - Lint TypeScript
Full Stack CI (.github/workflows/full-ci.yml) - Intégration complète - Tests end-to-end complets

Variables d’environnement 

Backend (.env)

DATABASE_URL=postgresql://koprogo:koprogo123@localhost:5432/koprogo_db
JWT_SECRET=your-super-secret-key-256-bits-min
SERVER_HOST=127.0.0.1
SERVER_PORT=8080
RUST_LOG=info

Frontend (.env)

PUBLIC_API_URL=http://127.0.0.1:8080

Déploiement 

Docker Production 

# Build des images
docker-compose build

# Démarrer en production
docker-compose up -d

# Vérifier les logs
docker-compose logs -f api
docker-compose logs -f frontend

Variables pour production 

# Backend
DATABASE_URL=postgresql://user:pass@prod-db:5432/koprogo_prod
JWT_SECRET=$(openssl rand -base64 32)
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

# Frontend
PUBLIC_API_URL=https://api.koprogo.com

Sécurité 

Bonnes pratiques implémentées 

Mots de passe: Bcrypt avec cost factor 12
JWT: Tokens avec expiration 24h
CORS: Configuration restrictive en production
SQL Injection: Requêtes paramétrées SQLx
XSS: Échappement automatique Svelte
Multi-tenant: Isolation par organization_id
Validation: Côté serveur avec validator crate

SuperAdmin par défaut 

Email: admin@koprogo.com
Password: admin123

⚠️ À CHANGER EN PRODUCTION!

Glossaire 

Building: Immeuble en copropriété géré par un syndic
Unit: Lot dans un immeuble (appartement, parking, cave)
Owner: Copropriétaire possédant un ou plusieurs lots
Expense: Charge ou dépense de copropriété
Organization: Entité multi-tenant (cabinet de syndic)
SuperAdmin: Administrateur plateforme avec accès universel
Syndic: Gestionnaire de copropriété
Accountant: Comptable avec accès limité aux finances

Ressources 

Documentation externe 

Liens projet 

Repository: (à définir)
Issues: (à définir)
Wiki: (à définir)

Contributeurs 

(Liste à compléter)

Licence 

(À définir)

Statut de la documentation 

Section	Statut	Dernière MAJ
Backend - Point d’entrée (main.rs, lib.rs, config.rs)	✅ Complet	2025-10-22
Backend - Entités (User, Building)	✅ Complet	2025-10-22
Backend - Autres entités	🚧 À faire
Backend - Use Cases	🚧 À faire
Backend - Repositories	🚧 À faire
Backend - Handlers	🚧 À faire
Frontend - Pages	🚧 À faire
Frontend - Composants	🚧 À faire
Frontend - Lib & Stores	🚧 À faire
Configuration & DevOps	🚧 À faire

Légende:

✅ Complet - Documentation détaillée avec exemples
🚧 À faire - Section à documenter
⚠️ Partiel - Documentation incomplète

—

Guides et Documentation Détaillée 

Documentation Projet

Business & Roadmap

Guides de Développement