---
title: Architecture
description: Vue d'ensemble de l'architecture technique de libreDecision
---

# Architecture

## Vue d'ensemble

libreDecision est organise en monorepo avec trois composants principaux :

```
libreDecision/
  backend/      # API Python FastAPI (port 8002)
  frontend/     # Application Nuxt 4 (port 3002)
  docker/       # Fichiers Docker et orchestration
  docs/         # Documentation (Nuxt Content)
```

## Stack technique

| Couche       | Technologie                                        |
| ------------ | -------------------------------------------------- |
| Frontend     | Nuxt 4 + Nuxt UI v3 + Pinia + UnoCSS              |
| Backend      | Python FastAPI + SQLAlchemy 2.0 (async) + Pydantic v2 |
| Base de donnees | PostgreSQL 16 (asyncpg)                         |
| Authentification | Duniter V2 Ed25519 challenge-response          |
| Sanctuaire   | IPFS (kubo) + hash on-chain (system.remark)        |
| CI/CD        | Woodpecker CI + Docker + Traefik                   |

## Domaines fonctionnels

L'application est decoupee en 5 domaines metier, chacun avec ses modeles, schemas, routes et services :

1. **Documents** -- Documents de reference modulaires (licence, engagements, reglement) composes d'items individuels versionnables.
2. **Decisions** -- Processus decisionnels multi-etapes (qualification, examen, vote, execution, rapport).
3. **Votes** -- Sessions de vote binaire ou nuance avec formule de seuil WoT, critere Smith et critere TechComm.
4. **Mandats** -- Mandats assignes a des membres (techcomm, forgeron, personnalise) avec cycle de vie complet.
5. **Protocoles** -- Configurations de formules de vote et protocoles de vote reutilisables.

Un domaine transversal, le **Sanctuaire**, assure l'archivage immuable via IPFS et ancrage on-chain.

## Principes d'architecture

- **Async everywhere** : toute la couche donnees et HTTP est asynchrone (asyncpg, AsyncSession, FastAPI async).
- **Separation modeles / schemas / routes / services** : chaque domaine suit ce decoupage strict.
- **API versionnee** : tous les endpoints sont sous `/api/v1/`.
- **Preuve cryptographique** : chaque vote est signe avec la cle Ed25519 du votant.
- **Vote permanent** : les documents de reference sont sous vote permanent, chaque item peut etre modifie par proposition et vote.

## Schema de communication

```
Navigateur
    |
    v
[Nuxt 4 Frontend] -- SSR/CSR, port 3000 (prod) / 3002 (dev)
    |
    v (fetch /api/v1/*)
[FastAPI Backend] -- port 8002
    |
    +---> [PostgreSQL 16] -- Donnees relationnelles
    +---> [IPFS kubo] -- Stockage distribue (Sanctuaire)
    +---> [Duniter V2 RPC] -- WoT, Smith, TechComm, system.remark
```

## Flux d'authentification

1. Le client envoie son adresse Duniter SS58 via `POST /api/v1/auth/challenge`.
2. Le serveur genere un challenge aleatoire (64 hex) et le stocke en memoire (TTL 5 min).
3. Le client signe le challenge avec sa cle privee Ed25519 et soumet via `POST /api/v1/auth/verify`.
4. Le serveur verifie la signature, cree ou retrouve l'identite `DuniterIdentity`, et retourne un token de session.
5. Le token est utilise en header `Authorization: Bearer <token>` pour les requetes authentifiees.

## Flux de vote

1. Un protocole de vote et sa formule sont crees ou selectionnes.
2. Une session de vote est creee avec un snapshot des tailles WoT/Smith/TechComm.
3. Les membres votent (binaire ou nuance) avec signature cryptographique.
4. A la cloture, le seuil WoT est calcule, les criteres Smith et TechComm sont verifies.
5. Le resultat (adopte/rejete) est archive dans le Sanctuaire (IPFS + on-chain).
