decision/docs/content/dev/2.architecture.md

title, description

title	description
Architecture	Vue d'ensemble de l'architecture technique de Glibredecision

Architecture

Vue d'ensemble

Glibredecision est organise en monorepo avec trois composants principaux :

Glibredecision/
  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).