Fonctionnement & logique principale

Démarrage

apps/server/src/index.ts :

1. appelle ensureDefaultRoles(), qui crée les rôles applicatifs admin (is_super_admin, ordre 0) et user (ordre 1) s'ils n'existent pas ;
2. monte les middlewares Hono (logger, cors) ;
3. monte Better Auth sur /api/auth/** ;
4. monte le RPCHandler oRPC sur /rpc/*, avec createContext() ;
5. expose les sondes de santé et GET /api/i18n.

CORS accepte localhost et 127.0.0.1 (tous ports) et l'origine CORS_ORIGIN, avec credentials: true.

Contexte et contrôle d'accès

• lib/context.ts : createContext() lit la session avec auth.api.getSession({ headers }).
• lib/orpc.ts :
  • publicProcedure : aucune vérification ;
  • protectedProcedure : exige une session, sinon UNAUTHORIZED ;
  • adminProcedure : exige user.role === "admin" (rôle Better Auth), sinon FORBIDDEN.
• middleware/update-last-connection.ts : sur les procédures protégées, met à jour user.last_connection sans bloquer la requête.

Le rôle Better Auth (user.role) et les rôles applicatifs (table roles) sont deux notions distinctes. Seul admin donne accès aux procédures admin. Voir Rôles & tags.

Procédures

Le nom des procédures est celui du code. Les entrées sont données dans leur forme principale ; les champs optionnels sont marqués ?.

Authentification (routers/auth.ts)

Fichiers (routers/naivi.ts)

processUploadedFile et processUploadedQA renvoient { success, fileId, jobId } dès la soumission du job, puis { success: false, error } si l'enregistrement échoue. Le résultat final (chunks ou paires) n'est pas renvoyé par ces procédures : il est inséré en base quand le job se termine.

Chunks

Les règles des chunks et des paires Q&A vivent dans un seul module, apps/server/src/utils/curated-item.ts :

• Un élément finetuned est en lecture seule : le serveur refuse de changer sa catégorie, de modifier son contenu et de le supprimer (BAD_REQUEST). La catégorie est posée hors du back office : aucune procédure ne l'accepte en création ni en changement.
• Modifier le contenu d'un élément efface son embedding, recalculé à la prochaine régénération de l'index.
• Insérer, supprimer ou catégoriser un élément recalcule le statut de son fichier : pending s'il n'a aucun élément ou si aucun n'est catégorisé, completed quand plus rien n'est not categorized, in_progress sinon.
• Une catégorisation en lot est vérifiée en entier avant toute écriture : un élément finetuned ou inconnu la rejette. Si un élément y figure deux fois, la dernière valeur s'applique.

Paires Q&A

Les paires suivent les mêmes règles que les chunks, ci-dessus.

Tags, rôles et associations

Voir Rôles & tags : getAllTags, createTag, updateTag, deleteTag, getAllRoles, createRole, updateRole, deleteRole, reorderRoles, getRoleTags, getAllRoleTags, getEffectiveRoleTags, setRoleTags, getItemTags, getItemTagsBatch, setItemTags, getFileTags, setFileTags, getUserRole, setUserRole.

Divers

Utilitaires métiers (utils/)

Étendre le serveur

• Nouvelle procédure : l'ajouter dans un routeur de apps/server/src/routers/, avec le bon niveau (publicProcedure, protectedProcedure, adminProcedure), puis la référencer dans routers/index.ts.
• Test d'accès obligatoire : chaque procédure doit figurer dans une seule liste de apps/server/tests/authorization.test.ts : PUBLIC, SIGNED_IN ou ADMIN_ONLY.
• Accès base : passer par db/index.ts et les schémas de db/schema/.
• Erreurs : lever une ORPCError avec un code (BAD_REQUEST, FORBIDDEN, etc.).