flowdeck/ARCHITECTURE.md

Architecture FlowDeck v1.0.0

Schéma

┌──────────────────────────────────────────────────────────┐
│                     Browser                              │
│  HTMX + Alpine.js + SortableJS + CSS Notion (31 KB)     │
└──────────────┬──────────────────────────────────────────┘
               │ HTTP (Jinja2 HTML / JSON API)
┌──────────────▼──────────────────────────────────────────┐
│              FastAPI (Python) — lifespan                 │
│  ┌──────────┬──────────┬──────────┬──────────┐         │
│  │ dashboard│  board   │  notes   │   api    │         │
│  │          │ 5 vues   │          │ CRUD     │         │
│  │          │ filtres  │          │ issues   │         │
│  │          │ tri      │          │ checklists│        │
│  │          │ props    │          │          │         │
│  └────┬─────┴────┬─────┴──────────┴────┬─────┘         │
│       │          │                     │                │
│  ┌────▼──────────▼─────────────────────▼─────┐          │
│  │        GiteaClient (httpx async)           │          │
│  └──────────────────┬────────────────────────┘          │
│                     │                                    │
│  ┌──────────────────▼────────────────────────┐          │
│  │           SQLite (WAL mode)               │          │
│  │  boards, cards, notes, col_mapping        │          │
│  │  checklists, checklist_items              │          │
│  │  project_properties, property_values      │          │
│  │  ai_keywords                              │          │
│  │  users, user_tokens                       │          │
│  └───────────────────────────────────────────┘          │
└──────────────────────┬───────────────────────────────────┘
                       │ HTTPS
┌──────────────────────▼───────────────────────────────────┐
│             Gitea API REST v1                             │
│  git.dracodev.net                                       │
└──────────────────────────────────────────────────────────┘

Flux de données

1. Dashboard → /api/v1/user/repos Gitea → liste projets avec sidebar
2. Board → /api/v1/repos/{o}/{r}/issues → cartes mappées sur colonnes
3. 5 vues → /board/{o}/{r}/view/{kanban|table|status|teamload|detailed} — fragments HTMX
4. Filtres → status=todo,progress&filter=assignee:X&sort=status:asc
5. Drag & drop → SortableJS → POST /api/move → BDD + Gitea labels
6. Propriétés custom → project_properties + property_values tables
7. AI Keywords → auto-extraction depuis labels + body → ai_keywords table
8. Sync → POST /board/api/sync/{o}/{r} → fetch + update + extract

Tables DB (12)

Table	Rôle
boards	Config Kanban par projet
cards	Position issues dans colonnes
col_mapping	Colonne → label Gitea
notes	Notes markdown
checklists	Checklists par issue
checklist_items	Items de checklist
users	Utilisateurs locaux
user_tokens	Tokens Gitea OAuth
project_properties	Propriétés custom par projet
property_values	Valeurs par issue
ai_keywords	Mots-clés auto-extraits

Routes (v1.0.0)

GET  /                                      → Dashboard
GET  /board/{owner}/{repo}                  → Board Kanban
GET  /board/{owner}/{repo}/view/{view}      → Fragment vue
GET  /board/api/properties/{o}/{r}          → Liste propriétés
POST /board/api/properties/{o}/{r}          → Créer propriété
DEL  /board/api/properties/{o}/{r}          → Supprimer propriété
POST /board/api/properties/{o}/{r}/values   → Set valeur propriété
GET  /board/api/ai-keywords/{o}/{r}         → Liste keywords
POST /board/api/ai-keywords/{o}/{r}/extract → Extraire keywords
POST /board/api/sync/{o}/{r}                → Sync complète

GET  /api/health                            → Health check
GET  /api/stats                             → Statistiques
GET  /api/projects                          → Projets JSON
POST /api/move                             → Déplacer carte
GET  /api/issues/{o}/{r}/{id}              → Issue detail (JSON)
GET  /api/issues/{o}/{r}/{id}?format=html  → Issue detail (HTML modal)
POST /api/issues/{o}/{r}                   → Créer issue
PATCH /api/issues/{o}/{r}/{id}             → Update issue
POST /api/checklists/{o}/{r}/{id}          → Créer checklist
POST /api/checklist-items/...              → Ajouter item
PATCH /api/checklist-items/{id}            → Toggle item

Décisions techniques

• SQLite: KISS, un fichier, pas de serveur
• HTMX + Alpine.js: Léger, pas de build step, fragments HTML
• CSS custom: Design system Notion, pas de framework CSS
• SortableJS: Drag & drop natif, pas de React dnd
• Jinja2 server-side: Templates côté serveur, HTMX pour interactivité