Vue d'ensemble du Web

L'application Web fournit une UI pour la gestion documentaire, l'annotation, le theming par bot et des tableaux de bord.

Stack

• React, TypeScript, Tailwind CSS
• Vite, TanStack Router, TanStack React Query
• Radix UI, Lucide Icons, next-themes
• ORPC (client/server RPC)

Rôle

• Interface principale pour les utilisateurs et les administrateurs.
• Gestion documentaire: upload, annotation des chunks et QA pairs, suivi de progression.
• Administration: tags, rôles applicatifs, assignations, régénération index FAISS.
• Personnalisation par personnalité de bot (branding, i18n depuis GET /api/i18n).

Architecture et références code

• Routage et entrée
  • apps/web/src/main.tsx initialise le router (@tanstack/react-router) et React Query.
  • apps/web/src/routes/ contient les routes groupées : (public)/, (auth)/, (protected)/, et __root.tsx.
• Appels API (RPC)
  • apps/web/src/utils/orpc.ts configure le client ORPC vers ${VITE_SERVER_URL}/rpc via RPCLink.
  • Gestion d'erreurs globale via QueryClient + QueryCache avec notifications sonner.
• Environnements (URLs au runtime)
  • apps/web/vite.config.ts injecte window.RUNTIME_ENV (VITE_SERVER_URL, VITE_CHATBOT_URL, VITE_BETTER_AUTH_CALLBACK_URL).
  • apps/web/src/utils/runtime-env.ts fournit getServerUrl(), getChatbotUrl().

Architecture et choix techniques

• Vite + React: DX rapide, HMR fiable, écosystème mature.
• TanStack Router/Query: routage moderne + data fetching/caching robuste.
• ORPC: client RPC typé → code simple et sûr.
• Shadcn/Radix: UI accessible et composable.

Périmètre et responsabilités

• UI des workflows: fichiers, chunks, QA, admin.
• Auth côté client et garde des routes (RBAC).
• Appels RPC vers le serveur et feedback UX (toasts, loaders).

Utilisation et extension

• Flux de démarrage: main.tsx → router + QueryClient. __root.tsx fournit layout, thème, providers.
• Routes: ajoutez des pages dans src/routes/(public|auth|protected)/ et déclarez vos loaders/actions.
• Appels API: utilisez utils/orpc.ts pour appeler /rpc. Gérez erreurs globales via QueryClient.
• Runtime env: getServerUrl() lit window.RUNTIME_ENV.VITE_SERVER_URL injecté par Vite/config.

Attention Better Auth: le client createAuthClient utilise VITE_SERVER_URL comme base URL. Sans préfixe /api/auth côté serveur, les endpoints attendus seront /sign-in/email, etc. Assurez-vous d’aligner la config local vs déployé.

i18n

Au démarrage, le frontend récupère les traductions depuis GET ${VITE_SERVER_URL}/api/i18n (ConfigMap Kubernetes ou fichier local). Cela permet de personnaliser les textes sans rebuild.

Fonctionnalités principales

Choix architecturaux

• Vite + React: DX rapide, HMR fiable.
• TanStack Router/Query: routage type-safe + data fetching avec cache.
• ORPC client typé: contrats forts avec le backend, zéro duplication de types.
• Shadcn/Radix UI: composants accessibles et composables.

Extension

• Nouvelle page: créez un fichier dans src/routes/(protected)/ ou (public)/, utilisez useQuery + orpc.{procedure}.queryOptions() pour les données.
• Nouveau hook: créez dans src/hooks/, exportez un useXxx() qui encapsule la logique TanStack Query.
• Nouveau composant UI: placez dans src/components/ui/ (Shadcn) ou src/components/ (générique).

Personnalisation

• Thème/branding: modifiez couleurs, logos et textes d’intro (pages publiques et layout).
• Pages/features: créez de nouveaux modules dans src/features/ et connectez-les aux routes.
• Auth: adaptez le guard des routes et le mapping des rôles (user/admin).
• Performances: utilisez React Query pour le cache, suspendez/optimisez les queries lourdes.