nAIxus Documentation

Installer l'environnement de développement nAIxus et lancer tous les services en 15 minutes.

Ce guide vous amène du git clone à un environnement de développement fonctionnel en 15 minutes.

Prérequis

Outil	Version	Vérification
Node.js	20+	`node -v`
pnpm	9+	`pnpm -v`
Python	3.13+	`python --version`
uv	latest	`uv --version`
Docker	20+	`docker --version`
Git	2.30+	`git --version`

Installer les outils manquants

# pnpm (via corepack)
corepack enable && corepack prepare pnpm@latest --activate

# uv (gestionnaire Python)
# Windows :
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS/Linux :
curl -LsSf https://astral.sh/uv/install.sh | sh

Étapes d'installation

1. Cloner et installer les dépendances frontend

git clone <REPO_URL> naixus-v2
cd naixus-v2
pnpm install

2. Installer les dépendances Python (services backend)

# Service Core
cd services/core
uv sync
cd ../..

# Service RAG
cd services/rag
uv sync
cd ../..

3. Configurer l'environnement

Créez un fichier .env à la racine du projet :

# Mode développement
NODE_ENV=development
ENVIRONMENT=development
DEBUG=true

# Base de données (SQLite pour le dev)
USE_SQLITE=true
SQLITE_DB_PATH=./data/naixus.db

# Chiffrement des secrets (générer une clé Fernet)
ENCRYPTION_KEY=<votre_clé_fernet>

# Fournisseur LLM (au moins un)
OPENAI_API_KEY=sk-...
# ou OLLAMA_BASE_URL=http://localhost:11434

Pour générer une clé Fernet :

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

4. Initialiser la base de données

# Appliquer les migrations Core
cd services/core
uv run alembic upgrade head
cd ../..

# Appliquer les migrations RAG (nécessite PostgreSQL + pgvector)
# Optionnel en dev si vous ne travaillez pas sur le RAG

5. Lancer tous les services

# Tout lancer via Turborepo
pnpm dev

Cela démarre en parallèle :

Service	Port	Description
Console Admin (Next.js)	3000	Interface d'administration
Core API (FastAPI)	8000	API principale
Yjs Server (WebSocket)	1234	Collaboration temps réel
Web Widget (Vite)	5173	Widget chat embarquable
Docs (TanStack Start)	3002	Site de documentation

6. Vérifier que tout fonctionne

# API Core
curl http://localhost:8000/health

# Console Admin
# Ouvrir http://localhost:3000 dans le navigateur

En mode développement, l'authentification est simplifiée : si aucun JWT n'est fourni, un utilisateur démo admin est automatiquement créé. Vous devez toujours fournir le header X-Tenant-ID.

Structure du monorepo

naixus-v2/
├── apps/
│   ├── console_admin/    # Next.js 16 — Admin UI
│   ├── web-widget/       # Vite + React — Widget chat
│   ├── docs/             # TanStack Start + Fumadocs — Documentation
│   └── yjs_server/       # Node.js — Serveur de collaboration
├── services/
│   ├── core/             # FastAPI — API principale + moteur d'exécution
│   └── rag/              # FastAPI — Service RAG (embeddings, retrieval)
├── packages/
│   ├── shared/           # Types TypeScript partagés
│   └── shared-python/    # Ports et utilitaires Python partagés
├── turbo.json            # Configuration Turborepo
├── pnpm-workspace.yaml   # Workspaces pnpm
└── docker-compose.yml    # Stack Docker (PostgreSQL, Redis)

Commandes utiles

Commande	Action
`pnpm dev`	Lancer tous les services en dev
`pnpm build`	Build complet (tous les apps)
`pnpm test`	Tests unitaires (Vitest + pytest)
`pnpm test:e2e`	Tests end-to-end (Playwright)
`pnpm lint`	Linting (ESLint + Ruff)
`pnpm lint:fix`	Auto-fix linting
`pnpm format`	Formatage (Prettier + Black)
`pnpm format:check`	Vérifier le formatage
`pnpm generate`	Générer le registre de nodes + types
`pnpm db:migrate`	Appliquer les migrations DB

Prochaines étapes

Architecture système — Comprendre comment les pièces s'assemblent
Standards de code — Conventions à respecter avant le premier PR
Guide de test — Écrire et lancer les tests

Démarrage rapide développeur