Architecture

Architecture technique de Sailor : Express API, React SPA, pipeline RAG, services externes.

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

1. Vue d'ensemble

Sailor est composé d'un backend Express.js monolithique et d'un frontend React/Vite. Le backend gère l'indexation documentaire, le pipeline RAG et les appels LLM. Aucune logique IA n'est exécutée côté client.

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

2. Backend — Architecture monolithique

Le backend est contenu dans server/index.js avec toutes les routes et la logique métier :

Domaine	Responsabilité
Workspaces	CRUD, isolation par slug
Upload	Parsing multi-format, chunking, embedding
Documents	Métadonnées, recherche, preview
Chat	Pipeline RAG complet (search → context → LLM → response)
Sessions	CRUD sessions de chat
Suggestions	Génération de questions contextuelles
Connectivité	Vérification périodique des APIs externes

3. Frontend — Structure

Couche	Responsabilité
Pages	HomePage, WorkspaceShell (container principal)
Composants	ChatPage, DocumentsPage, DocumentPanel, OnboardingWizard, Sidebar
Contexte	WorkspaceContext + useWorkspace hook
Client API	`lib/api.js` — clients global et workspace-scoped
Icons	Lucide React

HomePage (/)
  ↓ (sélection workspace)
WorkspaceShell (/:slug/*)
  ├── Onboarding (si non complété)
  ├── Chat (onglet principal)
  └── Documents (onglet secondaire)

5. Gestion de la connectivité

Sailor vérifie la disponibilité des APIs externes toutes les 60 secondes :

checkConnectivity()
  ├── Ping Mistral API
  │     ├── OK → isOnline = true
  │     └── Fail → isOnline = false (bascule Ollama)
  └── Vérifie modèle embedding disponible
        ├── Mistral Embed → Voyage AI → Ollama
        └── Sélectionne le premier disponible

Le changement de mode est transparent pour l'utilisateur. Un indicateur dans la sidebar affiche le mode courant (Local / Premium).

6. Services externes

Service	Usage	Fallback
Mistral Large	Chat LLM principal	Mistral Small → Ollama
Mistral Embed	Embedding des chunks	Voyage AI → Ollama nomic
Voyage AI	Embedding fallback	Ollama nomic-embed-text
Ollama	Mode 100% local	— (dernier niveau)

7. Configuration

PORT=3003
DB_PATH=./sailor.db
UPLOADS_DIR=./uploads
MISTRAL_API_KEY=...
MISTRAL_MODEL=mistral-large-latest
VOYAGE_API_KEY=...
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=ministral:3b
OLLAMA_EMBED_MODEL=nomic-embed-text