Architecture

Architecture technique de Pilot : Express API, React SPA, store, services externes.

REF-SPEC/AG001-ARCH v1.0 — 2026-04-09

1. Vue d'ensemble

Pilot est composé d'un backend Express.js et d'un frontend React/Vite séparés. Le backend expose une API REST avec streaming SSE pour les réponses IA. Aucune logique LLM n'est exécutée côté client.

┌─────────────────────────────────────────────────┐
│              Client (React + Vite)               │
│  WorkspaceContext ◄── API REST ──► Services       │
│  React Router          /api/*      externes       │
└───────────────────────┬─────────────────────────┘
                        │
         ┌──────────────┼──────────────┐
         │              │              │
    ┌────▼────┐   ┌─────▼─────┐  ┌────▼────┐
    │  SQLite │   │ Anthropic │  │ Mistral │
    │ (libsql)│   │  Claude   │  │   API   │
    └─────────┘   └───────────┘  └─────────┘
                        │
                  ┌─────▼─────┐
                  │  Ollama   │
                  │  (local)  │
                  └───────────┘

2. Backend — Modules

Module	Fichier	Responsabilité
Serveur principal	`server/index.js`	60+ routes API, upload, parsing, transformation
Matérialiseur	`server/materializer.js`	Pré-calcul des 4 vues analytiques
Query builder	`server/query-builder.js`	Conversion specs IA → requêtes SQL
Streaming	`server/stream.js`	Wrapper SSE pour réponses IA
Planificateur	`server/scheduler.js`	Gestion cron (node-cron)

3. Frontend — Structure

Couche	Responsabilité
Pages	HomePage, DashboardPage, ChatPage, ReportEditorPage, AdminPage, SchedulePage
Composants	25 composants React organisés par fonctionnalité
Contexte	WorkspaceProvider + useWorkspace hook
Client API	`lib/api.js` — factory `createWorkspaceApi(slug)`
Graphiques	Recharts (bar, pie, composed, area, table)
Éditeur	TipTap + @dnd-kit

HomePage (/)
  ↓ (sélection workspace)
WorkspaceShell (/:slug/*)
  ├── /dashboard         — Liste rapports + vue d'ensemble
  ├── /editor/new        — Nouveau rapport vierge
  ├── /editor/:id        — Édition rapport existant
  ├── /report/:id        — Vue rapport plein écran
  ├── /chat              — Chat explorateur IA
  ├── /schedules         — Plannings récurrents
  ├── /admin             — Contexte et statistiques
  └── /trash             — Rapports supprimés

5. Modes IA

Pilot supporte un double mode IA basculable à chaud :

Mode Premium (par défaut)

Priorité	Modèle	Usage
1	Claude claude-sonnet-4-20250514	Génération principale
2	Mistral 3B (cloud)	Fallback si Claude indisponible
3	Ollama (local)	Dernier recours

Mode Local (offline)

Modèle	Usage
Ollama + Ministral 3B	100% local, aucune donnée envoyée au cloud

Le mode est sélectionnable depuis la sidebar. Le changement s'applique immédiatement à toutes les opérations IA.

6. Services externes

Service	Usage	Coût estimé
Anthropic Claude	Génération rapports, chat, suggestions	Variable
Mistral API	Fallback LLM cloud	Négligeable
Ollama	Mode offline	Gratuit (local)