Fonctionnement & logique principale

Serveur HTTP: Hono, RPC via ORPC, sessions via Better Auth.
Flux: Requête Web → CORS/Logger → Auth (si /api/auth/**) → ORPC /rpc/* → REST endpoints → Handlers.
Données: PostgreSQL via Drizzle (schemas auth et naivi).

Initialisation au démarrage

apps/server/src/index.ts exécute ensureDefaultRoles() au démarrage: crée les rôles admin (isSuperAdmin: true) et user (isSuperAdmin: false) s'ils n'existent pas encore dans la table roles.

Points d'entrée

apps/server/src/index.ts
- Middlewares: logger, cors (origines dynamiques + CORS_ORIGIN), credentials: true.
- Auth Better Auth monté sur POST/GET /api/auth/** → auth.handler().
- ORPC: new RPCHandler(appRouter) monté sur /rpc/* avec createContext().
- Santé: GET /, GET /health, GET /ready retournent OK.
- i18n REST: GET /api/i18n — sert les traductions frontend depuis I18N_JSON (env), /app/i18n.json (Docker), ou ../../i18n.json (local).
- Debug: GET /api/i18n/debug — diagnostique les chemins de fichiers i18n.
apps/server/src/lib/context.ts
- createContext() lit la session: auth.api.getSession({ headers }).
- Met à jour user.lastConnection quand l'utilisateur est authentifié.
apps/server/src/lib/orpc.ts
- publicProcedure — accessible sans auth.
- protectedProcedure — exige une session valide, sinon UNAUTHORIZED.
- adminProcedure — exige role === 'admin', sinon FORBIDDEN.

Routeur RPC

apps/server/src/routers/index.ts agrège:

export const appRouter = {
  healthCheck,  // public
  i18n,         // public — retourne les données i18n depuis le ConfigMap/fichier
  ...authRouter,
  ...naiviRouter,
  ...rolesTagsRouter,
};

Handlers Auth — `apps/server/src/routers/auth.ts`

Procédure	Accès	Description
`getMe`	public	Retourne l'utilisateur courant ou `null`
`getAllUsers`	protégé	Liste tous les utilisateurs
`getUserNames`	protégé	Retourne id+nom de tous les utilisateurs
`getUserbyId`	admin	Utilisateur par ID
`getUserbyEmail`	admin	Utilisateur par email
`getUserLastConnection`	admin	Dernière connexion d'un utilisateur

Handlers Naivi — `apps/server/src/routers/naivi.ts`

Fichiers (table unifiée `files`)

Procédure	Accès	Input	Description
`getFiles`	protégé	`{ type: "regular" \| "qa" }`	Liste les fichiers par type avec infos d'assignation
`getUserFiles`	protégé	`{ userId, type }`	Fichiers assignés à un utilisateur
`updateFileName`	protégé	`{ fileId, name, userId }`	Renomme un fichier (sauvegarde l'ancien nom dans `old_name`)
`updateFileStatus`	protégé	`{ fileId, status, userId }`	Mise à jour du statut de classification
`deleteFile`	admin	`{ fileId, deleterId }`	Supprime un fichier et ses enfants (cascade)
`getFileName`	protégé	`{ fileId }`	Retourne le nom d'un fichier
`getFileHistory`	protégé	`{ fileId }`	Retourne `old_name`
`getFileAssignments`	protégé	`{ fileId }`	Retourne les assignations d'un fichier
`assignFileToUsers`	admin	`{ fileId, userIds[], assignedBy }`	Assigne un fichier à plusieurs utilisateurs
`processUploadedFile`	admin	`{ fileContent, fileName, fileType, uploaderId, chunkSize, overlap }`	Upload + chunking via document-processor microservice
`processUploadedQA`	admin	`{ fileContent, fileName, fileType, uploaderId }`	Upload + parsing CSV Q&A

Chunks

Procédure	Accès	Input	Description
`getFileChunks`	protégé	`{ fileId }`	Chunks d'un fichier, triés par `rank`
`updateChunksCategory`	protégé	`[{ chunkId, category, userId }]`	Mise à jour en lot des catégories
`updateChunkContent`	protégé	`{ chunkId, content, userId }`	Modifie le contenu (sauvegarde dans `old_content`)
`deleteChunk`	protégé	`{ chunkId, userId }`	Supprime un chunk
`getChunkCategory`	protégé	`{ chunkId }`	Retourne la catégorie d'un chunk
`getChunkHistory`	protégé	`{ chunkId }`	Retourne `old_content`
`insertChunk`	protégé	`{ fileId, rank, content, category, userId }`	Insère un chunk à un rang précis
`addManualChunk`	admin	`{ content, category, userId }`	Crée un chunk sans fichier parent
`getFileProgress`	protégé	`{ fileId }`	Progression de classification (chunks)

QA Pairs

Procédure	Accès	Input	Description
`getQasFromFile`	protégé	`{ fileId }`	QA pairs d'un fichier, triés par `rank`
`updateQaPair`	protégé	`{ id, question?, answer?, userId }`	Modifie question/réponse
`updateQaPairCategory`	protégé	`{ id, category, userId }`	Catégorie d'une paire
`updateQaPairsCategory`	protégé	`[{ id, category, userId }]`	Mise à jour en lot des catégories
`deleteQaPair`	protégé	`{ id, userId }`	Supprime une paire
`getQaPairHistory`	protégé	`{ pairId }`	Retourne `old_question` + `old_answer`
`insertQAPair`	protégé	`{ fileId, rank, question, answer, category, userId }`	Insère une paire à un rang précis
`addManualQAPair`	admin	`{ question, answer, category, userId }`	Crée une paire sans fichier parent
`getQaFileProgress`	protégé	`{ fileId }`	Progression de classification (QA pairs)

Divers

Procédure	Accès	Description
`getLogo`	public	Retourne le logo actif (exclut `logo_dark`/`logo_light`), données en base64
`regenerateIndex`	admin	Appelle `POST ${INDEX_API_URL}/regenerate-index` pour régénérer les index FAISS

Handlers Roles & Tags — `apps/server/src/routers/roles-tags.ts`

Voir la page dédiée server/roles-tags.mdx pour le détail complet. Résumé:

Tags CRUD: getAllTags, createTag, updateTag, deleteTag (admin)
Roles CRUD: getAllRoles, createRole, updateRole, deleteRole, reorderRoles (admin)
Associations role-tag: getRoleTags, getAllRoleTags, getEffectiveRoleTags, setRoleTags (admin)
Associations item-tag: getItemTags, getItemTagsBatch (protégé), setItemTags (admin)
Gestion rôle utilisateur: getUserRole (protégé), setUserRole (admin)

Utilitaires métiers

Fichier	Responsabilité
`utils/regular-processing.ts`	Upload fichier → appel document-processor → insertion chunks en DB
`utils/qa-processing.ts`	Parsing CSV Q&A → insertion qa_pair en DB
`utils/chunk-operations.ts`	CRUD chunks: catégorie, contenu, suppression, progression
`utils/file-operations.ts`	Renommage fichier, statut de classification, assignations
`utils/qa-operations.ts`	CRUD qa_pair: update question/réponse/catégorie, suppression
`utils/manual-operations.ts`	Ajout de chunk/QA pair manuel (sans fichier parent)
`utils/document-processor-client.ts`	Client HTTP vers le microservice `document-processor`
`utils/sanitize.ts`	Sanitisation de texte pour PostgreSQL
`utils/user-operations.ts`	Mise à jour `lastConnection` utilisateur

Extension

Nouveau handler ORPC: créez une méthode dans apps/server/src/routers/*.ts, utilisez publicProcedure/protectedProcedure/adminProcedure, exportez via spread dans routers/index.ts.
Contexte: ajoutez des infos dans createContext() si vos handlers en ont besoin.
Accès DB: passez par apps/server/src/db/index.ts et apps/server/src/db/schema/*.ts pour requêtes typées Drizzle.
Erreurs: standardisez via les utilitaires ORPC (ORPCError) pour une gestion uniforme côté Web.

Server Functioning & Core Logic