nAIxus Documentation

Vue d'ensemble des applications frontend, stack technique, patterns et structure du code.

Le monorepo contient trois applications frontend et un serveur de collaboration. Ce document couvre leur stack, leur structure et leurs patterns.

Applications

App	Framework	Port	Rôle
Console Admin	Next.js 16 (App Router)	3000	Interface d'administration principale
Web Widget	Vite + React	5173	Widget chat embarquable
Docs	TanStack Start + Fumadocs	3002	Site de documentation
Yjs Server	Node.js (WebSocket)	1234	Serveur de collaboration temps réel

Console Admin — Stack technique

Dépendances clés

Bibliothèque	Version	Rôle
Next.js	16.1.6	Framework React avec SSR/SSG
React	19.2.4	Bibliothèque UI
Radix UI + shadcn/ui	—	Composants UI accessibles
Tailwind CSS	4.x	Styles utilitaires
Zustand	5.0.11	State management global
TanStack Query	5.90.20	Data fetching + cache
React Hook Form	7.71.1	Gestion de formulaires
Zod	4.3.6	Validation de schémas
@xyflow/react	12.10.1	Éditeur de flows (canvas)
Yjs	13.6.29	Collaboration temps réel (CRDT)
Monaco Editor	0.55.1	Éditeur de code (node Code)
Tiptap	—	Éditeur rich text (prompts)

Structure du code

apps/console_admin/
├── app/                    # Routes Next.js (App Router)
│   ├── layout.tsx          # Layout racine
│   ├── page.tsx            # Page d'accueil
│   ├── flows/              # Pages flows
│   ├── channels/           # Pages channels
│   ├── agents/             # Pages agents/templates
│   └── history/            # Historique des exécutions
├── components/             # Composants partagés
│   ├── ui/                 # Primitives shadcn/ui (Button, Dialog, etc.)
│   ├── app-sidebar.tsx     # Navigation principale
│   └── header.tsx          # Header de l'application
├── features/               # Code organisé par domaine
│   ├── flows/
│   │   ├── components/     # Composants spécifiques aux flows
│   │   ├── hooks/          # Hooks custom (useFlowStore, etc.)
│   │   ├── types/          # Types Flow, Node, Edge
│   │   └── utils/          # Utilitaires de manipulation de flows
│   ├── channels/
│   ├── collaboration/      # Yjs integration
│   ├── transcripts/
│   └── devtools/
├── types/                  # Types globaux
└── tests/                  # Tests (Vitest + Playwright)

Patterns de state management

L'application utilise une approche en couches :

Type d'état	Outil	Quand l'utiliser
Données serveur	TanStack Query	Toute donnée venant de l'API (flows, runs, channels)
État global UI	Zustand	Sidebar ouverte, thème, préférences
État formulaire	React Hook Form + Zod	Tout formulaire (création de flow, config de node)
État collaboratif	Yjs (CRDT)	Canvas de flow, édition collaborative
État local	`useState` / `useReducer`	État éphémère d'un composant
État URL	`useSearchParams`	Filtres, pagination, onglet actif

Arbre de décision

Data fetching

Pattern standard avec TanStack Query :

// Hook de récupération
function useFlows(tenantId: string) {
  return useQuery({
    queryKey: ['flows', tenantId],
    queryFn: () => fetchFlows(tenantId),
  });
}

// Mutation avec invalidation
function useCreateFlow() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: createFlow,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['flows'] });
    },
  });
}

Composants UI

Les composants suivent les patterns shadcn/ui :

Primitives Radix UI pour l'accessibilité (focus, keyboard, aria).
Tailwind pour le style via className et cn() utility.
Variants via class-variance-authority (cva) pour les variantes de composants.

Architecture

Le widget est un bundle JavaScript autonome qui s'intègre dans n'importe quel site via un tag <script>. Il utilise le Shadow DOM pour isoler ses styles du site hôte.

apps/web-widget/src/
├── widget.ts           # Point d'entrée (API d'embedding)
├── App.tsx             # Composant racine
├── api/                # Client API (connexion au Core)
├── components/         # Composants chat
├── hooks/              # Hooks custom
├── ui/                 # Composants UI de base
└── storage/            # Persistence locale (session)

Stack spécifique

Vercel AI SDK pour le streaming LLM côté client.
Shadow DOM pour l'isolation CSS totale.
react-markdown + remark-gfm pour le rendu Markdown des réponses.
jest-axe pour les tests d'accessibilité.

Collaboration temps réel (Yjs)

Comment ça fonctionne

Le Yjs Server (apps/yjs_server/) maintient un Y.Doc par flow.
Chaque client (navigateur) se connecte via WebSocket.
Les modifications du canvas (ajout/déplacement de nodes, edges) sont synchronisées via CRDT.
Les curseurs des autres utilisateurs sont visibles via le protocole Awareness de Yjs.
L'état est persisté dans PostgreSQL côté serveur.

Authentification

Le Yjs Server valide les JWT dans les frames WebSocket pour s'assurer que seuls les utilisateurs autorisés accèdent aux documents.

Packages partagés

`packages/shared/`

Types TypeScript et utilitaires partagés entre les apps frontend :

Types communs (Flow, Node, Channel, etc.)
Client de base de données Kysely (pour le Yjs Server)
Exporté via @naixus/shared

Tests frontend

Type	Framework	Emplacement	Commande
Unitaire	Vitest + Testing Library	`tests/unit/`	`pnpm test`
E2E	Playwright	`tests/e2e/`	`pnpm test:e2e`
Accessibilité	jest-axe (widget)	Inline avec les tests unitaires	`pnpm test`

Pour aller plus loin

Architecture système — Vue d'ensemble de tous les services
Standards de code — Conventions TypeScript/ESLint
Guide de test — Comment tester les composants

Architecture frontend