Server Overview
Vue d'ensemble du serveur
Le serveur (apps/server) est l'API backend de l'application web de back-office. Il gère l'authentification, la base PostgreSQL, le pipeline d'ingestion des documents, la curation des chunks et des paires Q&A, les tags et rôles, et déclenche la régénération des index.
Le chat ne passe pas par le serveur : il est servi par rag-agent, qui lit les index et la base directement.
Stack
| Technologie | Usage |
|---|---|
| Bun | Runtime TypeScript |
| Hono | Serveur HTTP, CORS, logs |
oRPC (@orpc/server) | Procédures RPC typées, exposées sous /rpc/* |
Drizzle ORM + pg | Accès PostgreSQL, migrations |
| Better Auth | Sessions, OAuth Microsoft, plugin admin |
| Zod | Validation des entrées des procédures |
Responsabilités
- Authentification et sessions (Better Auth). Contrôle d'accès des procédures :
protectedProcedureetadminProcedure. - Ingestion : upload, envoi à
document-processoren job asynchrone, insertion des chunks et des tags. - Curation : catégories, tags, contenu et historique des chunks et des paires Q&A.
- Rôles et tags applicatifs, qui déterminent le contenu de chaque index.
- Régénération des index : appel de l'API d'index de
rag-agent(INDEX_API_URL). - Santé :
GET /,GET /healthetGET /readyrépondentOK. - Traductions :
GET /api/i18n. - Création des rôles applicatifs
adminetuserau démarrage.
Routes HTTP
| Route | Rôle |
|---|---|
POST/GET /api/auth/** | Better Auth |
/rpc/* | Procédures oRPC |
GET /api/i18n | Traductions frontend (variable I18N_JSON, sinon fichier i18n.json) |
GET /, GET /health, GET /ready | Sondes de santé |
Routeurs oRPC
| Routeur | Fichier | Périmètre |
|---|---|---|
authRouter | routers/auth.ts | Utilisateurs |
naiviRouter | routers/naivi.ts | Fichiers, chunks, paires Q&A, logo, index, feedback, transcription |
rolesTagsRouter | routers/roles-tags.ts | Tags, rôles, associations |
healthCheck, i18n | routers/index.ts | Procédures publiques |
Le détail des procédures est dans Fonctionnement & logique principale.
Variables d'environnement clés
| Variable | Description |
|---|---|
DATABASE_URL | Base PostgreSQL principale (schémas auth et naivi) |
CHAINLIT_DATABASE_URL | Base Chainlit, lue pour le logo et les feedbacks |
BETTER_AUTH_SECRET, BETTER_AUTH_URL | Better Auth |
CORS_ORIGIN | Origine du front autorisée (utilisée aussi comme trustedOrigins) |
MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_TENANT_ID | OAuth Microsoft |
DOCUMENT_PROCESSOR_URL | URL de document-processor (défaut dans le code : http://localhost:8001) |
INDEX_API_URL | URL de l'API d'index de rag-agent ; sans elle, regenerateIndex échoue |
I18N_JSON | Traductions en JSON inline |
LITELLM_API_BASE, LITELLM_API_KEY, TRANSCRIPTION_MODEL_ID | Transcription audio (transcribeAudio) |
La liste complète et les valeurs d'exemple sont dans .env.example à la racine du dépôt et dans la page Déploiement.
Contrat des procédures
Une procédure oRPC lève une ORPCError en cas d'échec et renvoie son payload en cas de succès. Le client gère les erreurs avec try/catch.
Quelques procédures renvoient encore une enveloppe { success, error } : processUploadedFile, processUploadedQA, regenerateIndex et les helpers d'ajout manuel. Cette forme est à considérer comme un écart au contrat, pas comme la norme.
Choix techniques
- Bun + Hono : démarrage rapide, peu de surcharge, API Web standards.
- oRPC : contrat typé entre le front et le back, middlewares de contrôle d'accès.
- Drizzle : schéma TypeScript, migrations SQL versionnées.
- Better Auth : sessions, OAuth Microsoft, plugin
admin. - document-processor séparé : les dépendances de parsing (Docling, PyTorch) restent hors du runtime TypeScript.