nAIxus Documentation

Vue d'ensemble de l'architecture nAIxus, des services, et de leurs interactions.

nAIxus est un monorepo composé de deux services backend (Core, RAG), trois applications frontend (Console Admin, Web Widget, Docs), et un serveur de collaboration temps réel (Yjs).

Services

Core API (`services/core/`)

Le cœur de nAIxus. Gère les flows, l'exécution, les channels, les tenants et l'authentification.

Responsabilité	Détails
Gestion des flows	CRUD, versioning, templates
Moteur d'exécution	Traversée du graphe de nodes, résolution des expressions, exécution séquentielle
Channels	Gestion des points de déploiement (SDK, Webchat, Slack, Teams, WhatsApp)
LLM orchestration	Appel aux fournisseurs IA via des adapters (OpenAI, Anthropic via Azure, Bedrock, WatsonX, Ollama, vLLM)
Multi-tenant	Isolation complète des données par tenant
Streaming SSE	Événements temps réel pour l'exécution des flows
Authentification	JWT (Keycloak-compatible) avec isolation par tenant

Stack : FastAPI, SQLAlchemy 2 (async), Alembic, Pydantic Settings, structlog

RAG API (`services/rag/`)

Service séparé pour le Retrieval-Augmented Generation. Gère l'ingestion de documents, l'embedding, et la recherche sémantique.

Responsabilité	Détails
Connecteurs	SharePoint, S3, upload de fichiers
Ingestion	Parsing (PDF, DOCX, PPTX, HTML), chunking, embedding
Vectorstore	pgvector pour la recherche sémantique
Recherche hybride	Vectorielle + lexicale (tsvector) + reranking
Knowledge Bases	Regroupement de documents par base de connaissances

Stack : FastAPI, SQLAlchemy 2, pgvector, sentence-transformers, Redis Streams (file de tâches)

Console Admin (`apps/console_admin/`)

L'interface d'administration principale. C'est là que les utilisateurs conçoivent les flows, configurent les channels, et supervisent les exécutions.

Stack : Next.js 16 (App Router), React 19, Radix UI + shadcn/ui, Tailwind 4, Zustand, TanStack Query, React Hook Form + Zod, @xyflow/react (éditeur de flows), Yjs (collaboration), Monaco Editor

Widget chat embarquable que les clients intègrent dans leurs sites web. Se connecte au Core API via streaming (Vercel AI SDK).

Stack : Vite, React 19, Vercel AI SDK, Shadow DOM (isolation CSS)

Yjs Server (`apps/yjs_server/`)

Serveur WebSocket qui synchronise l'état des flows entre plusieurs collaborateurs en temps réel (CRDT via Yjs).

Stack : Node.js pur, Yjs, WebSocket, PostgreSQL (persistance), JWT (authentification des frames WebSocket)

Architecture hexagonale

Les deux services backend suivent strictement l'architecture hexagonale (Ports & Adapters) :

Règle de dépendance : Le code au centre (domaine) ne dépend jamais du code extérieur (infrastructure). Les ports (interfaces Python Protocol) sont définis dans la couche application, les adapters les implémentent dans la couche infrastructure.

Pour les détails de chaque couche, voir Architecture backend.

Multi-tenancy

Chaque requête porte un X-Tenant-ID dans les headers. La couche d'authentification :

Valide le JWT.
Vérifie que le tenant demandé est dans la liste des tenants autorisés de l'utilisateur.
Injecte un TenantContext dans le cycle de vie de la requête.
Tous les repositories filtrent automatiquement par tenant_id.

Données partagées

Le package packages/shared-python/ fournit les ports et utilitaires communs aux deux services backend (Core et RAG) :

Ports : SecretsPort, LoggerPort
Modèles de base SQLAlchemy
Utilitaires de chiffrement

Le package packages/shared/ fournit les types TypeScript partagés entre les apps frontend et le Yjs Server.

Pour aller plus loin

Démarrage rapide — Installation de l'environnement
Architecture backend — Détail des couches hexagonales
Référence API — Endpoints REST
Frontend — Architecture des apps frontend

Architecture système

Vue d'ensemble