# Architecture FlowDeck

## Schéma

```
┌──────────────────────────────────────────────┐
│                  Browser                      │
│  HTMX + Alpine.js + SortableJS               │
└──────────────┬───────────────────────────────┘
               │ HTTP (Jinja2 HTML / JSON API)
┌──────────────▼───────────────────────────────┐
│              FastAPI (Python)                 │
│  ┌──────────┬──────────┬──────────┐          │
│  │ dashboard│  board   │  notes   │   api    │
│  └────┬─────┴────┬─────┴──────────┴────┬─────┘
│       │          │                     │
│  ┌────▼──────────▼─────────────────────▼─────┐
│  │        GiteaClient (httpx async)           │
│  │  repos, issues, labels, milestones         │
│  └──────────────────┬────────────────────────┘
│                     │
│  ┌──────────────────▼────────────────────────┐
│  │           SQLite (WAL mode)                │
│  │  boards, cards, notes, col_mapping         │
│  └───────────────────────────────────────────┘
└──────────────────────┬────────────────────────┘
                       │ HTTPS
┌──────────────────────▼────────────────────────┐
│             Gitea API REST v1                  │
│  git.dracodev.net                             │
└───────────────────────────────────────────────┘
```

## Flux de données

1. **Dashboard** : appelle `/api/v1/user/repos` + `/api/v1/user/orgs` Gitea → affiche liste projets
2. **Board** : appelle `/api/v1/repos/{owner}/{repo}/issues` → mappe sur colonnes via BDD locale
3. **Drag & drop** : SortableJS → `POST /api/move` → mise à jour SQLite + sync Gitea (labels/close)
4. **Notes** : stockées en SQLite local (non sync Gitea)

## Décisions techniques

- **SQLite (pas PostgreSQL)** : KISS. Un fichier, pas de serveur. Migration future triviale via Alembic si besoin.
- **HTMX + Alpine.js (pas React)** : Léger, progressif. Pas de build step.
- **Cache Gitea in-memory** : TTL configurable, pas de Redis. Suffisant pour <100 repos.
- **Pas d'auth OAuth en v0.2** : token global Gitea. OAuth par utilisateur prévu v0.3.
- **Pas de webhooks** : polling implicite au refresh. Webhooks prévus v0.4.

## Base de données

```
boards           → config Kanban par projet (colonnes, WIP)
cards            → position des issues dans les colonnes
notes            → notes markdown par projet
col_mapping      → mapping colonne→label Gitea (sync bidirectionnelle)
```

## Routes

```
GET  /                         → Dashboard projets
GET  /board/{owner}/{repo}     → Board Kanban
GET  /notes/{owner}/{repo}     → Notes markdown
POST /notes/{owner}/{repo}     → Sauvegarder notes
GET  /api/health               → Health check
GET  /api/stats                → Statistiques
GET  /api/projects             → Projets (JSON)
POST /api/move                 → Déplacer carte
POST /api/col-mapping          → Config mapping colonne→label
GET  /api/board-config/{o}/{r} → Config board
POST /api/board-config/{o}/{r} → MàJ config board
```