_____             _     _____
  / ____|           | |   |_   _|   /\
 | (___   ___  _ __ | |__   | |    /  \
  \___ \ / _ \| '_ \| '_ \  | |   / /\ \
  ____) | (_) | |_) | | | |_| |_ / ____ \
 |_____/ \___/| .__/|_| |_|_____/_/    \_\
              | |
              |_|

• ✨ À propos
• 🎯 Demo & Visuels
• 🚀 Quick Start
• 🏗️ Architecture
• 📚 Documentation
• 💻 Development
• 🚢 Deployment
• 🗺️ Roadmap
• 🤝 Contributing
• 🛡️ Security
• 📊 Performance
• 📄 License
• 💬 Support & Contact

SophIA est une plateforme SaaS de chat conversationnel intelligent qui permet aux entreprises d'interagir avec leurs documents de manière naturelle et efficace grâce à l'intelligence artificielle avancée.

SophIA incarne l'intelligence au service de la connaissance. Tel que la sagesse antique guidait les décisions, SophIA transforme vos documents en conversations éclairées, rendant l'information accessible et actionnable.

Notre mission : démocratiser l'accès à l'information en transformant des documents complexes en conversations naturelles, alimentées par l'IA la plus avancée de Google (Gemini 2.5 Flash).

La sagesse consiste à rendre complexe accessible — SophIA y parvient en combinant :

• 🧠 Intelligence : Compréhension profonde avec Gemini 2.5 Flash
• 📚 Connaissance : RAG précis avec Qdrant et embeddings avancés
• 🤝 Service : Interface conversationnelle intuitive et réactive
• ⚖️ Équilibre : Puissance IA + contrôle des coûts + sécurité

• Support Client : Recherche instantanée dans la documentation produit
• Analyse Juridique : Questions sur contrats et documents légaux
• Knowledge Management : Centralisation et recherche dans la base de connaissances
• R&D : Veille technologique et extraction d'insights depuis articles scientifiques

L'architecture de SophIA est conçue pour atteindre les objectifs suivants :

Note : Ces objectifs sont basés sur l'architecture mise en place (Docker Compose, résilience, monitoring). Des tests de charge sont nécessaires pour valider les performances en conditions réelles.

┌─────────────────────────────────────────────────────────────┐
│                    UTILISATEURS                              │
│   Web (Next.js 15) • Mobile (Flutter) • API Clients         │
└─────────────────────┬───────────────────────────────────────┘
                      │ HTTPS + gRPC-Web
           ┌──────────▼──────────┐
           │    ENVOY PROXY      │  TLS • Load Balancing • Rate Limiting
           └──────────┬──────────┘
                      │ gRPC (HTTP/2)
┌─────────────────────▼───────────────────────────────────────┐
│              BACKEND (Node.js 20 + Fastify)                  │
│  • ChatService (streaming)    • DocumentService (upload)     │
│  • RagService (search)        • CostService (quotas)         │
│                                                               │
│  Middlewares: Auth • Validation • Tracing • Rate Limiting    │
└────────┬──────────────┬──────────────┬─────────────┬────────┘
         │              │              │             │
    ┌────▼────┐   ┌────▼────┐   ┌────▼────┐   ┌────▼────┐
    │Postgres │   │ Qdrant  │   │  Redis  │   │  MinIO  │
    │   16    │   │  1.15   │   │    7    │   │   S3    │
    │  +RLS   │   │ 1536d   │   │BullMQ+  │   │  R2     │
    │         │   │ Vector  │   │ Cache   │   │  Docs   │
    └─────────┘   └─────────┘   └─────────┘   └─────────┘

Document Upload (PDF, DOCX, PPTX)
    │
    ├─► OCR (Docling - IBM Granite)
    │
    ├─► Markdown Extraction Unifié
    │
    ├─► Chunking Sémantique (remark/unified)
    │       • Préserve headers, tables, listes
    │       • Chunks adaptatifs (512-2048 tokens)
    │
    ├─► Embeddings (gemini-embedding-001, 1536 dims)
    │       • Batch processing pour optimiser coûts
    │
    ├─► Indexation Qdrant
    │       • Collection par user: docs_{userId}
    │       • Metadata: userId, documentId, pageNumber
    │
    └─► Recherche Hybride
            • Vectorielle (similarité cosine)
            • Filtres metadata (userId, dates)
            • Cache Redis (60% réduction latence)

• Node.js 20 LTS (nvm recommandé)
• Docker Desktop 4.x+ (avec Rosetta 2 pour Mac M-series)
• Git 2.x+
• 16GB+ RAM recommandé

# 1. Cloner le projet
git clone <repo>
cd SophIA

# 2. Installer les dépendances
npm install

# 3. Configurer l'environnement
cp .env.example .env.local
# Éditer .env.local avec vos credentials (voir section Configuration)

# 4. Démarrer l'infrastructure (PostgreSQL, Redis, Qdrant, MinIO)
docker compose up -d

# 5. Appliquer les migrations de base de données
npm run db:migrate:deploy

# 6. Démarrer les applications (3 terminaux)

# Terminal 1 - Backend gRPC
cd apps/backend && npm run dev

# Terminal 2 - Worker BullMQ
cd apps/worker && npm run dev

# Terminal 3 - Frontend Next.js
cd apps/frontend && npm run dev

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/sophia"

# Redis
REDIS_HOST="localhost"
REDIS_PORT="6379"
REDIS_PASSWORD="your-redis-password"

# Qdrant
QDRANT_URL="http://localhost:6333"
QDRANT_API_KEY="dev_api_key_change_in_production"

# MinIO (dev) / Cloudflare R2 (prod)
S3_ENDPOINT="http://localhost:9000"
S3_ACCESS_KEY="minioadmin"
S3_SECRET_KEY="minioadmin"
S3_BUCKET="documents"

# Google Vertex AI (Gemini)
VERTEX_AI_PROJECT_ID="your-gcp-project-id"
VERTEX_AI_LOCATION="us-central1"
GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

# Authentication (Better Auth)
BETTER_AUTH_SECRET="your-secret-key-minimum-32-chars"
BETTER_AUTH_URL="http://localhost:3000"

# JWT
JWT_SECRET="your-jwt-secret-minimum-32-chars"

# Environment
NODE_ENV="development"

# Health check backend
curl http://localhost:3000/health

# Tester gRPC (grpcurl requis)
grpcurl -plaintext localhost:50051 list

# Voir les logs
docker compose logs -f

# Statut des services
docker compose ps

• Framework: Next.js 15 (App Router, React 19, Server Components)
• UI: shadcn/ui + Radix UI + Tailwind CSS 4.0
• State: Zustand + React Query (TanStack Query)
• API: gRPC-Web via @connectrpc/connect-web
• Language: TypeScript 5.7 (strict mode)

• Runtime: Node.js 20 LTS
• Framework: Fastify 5.6+ (performance-first)
• RPC: Connect (gRPC compatible, HTTP/2)
• ORM: Prisma 6.17 (type-safe, auto-migrations)
• DI: InversifyJS (Hexagonal Architecture)
• Validation: Zod (end-to-end type safety)
• Auth: Better Auth (email/password + OAuth)
• Logging: Pino (structured JSON logs)
• Tracing: OpenTelemetry + Jaeger
• Language: TypeScript 5.7 (strict mode)

• Queue: BullMQ 5.61+ (Redis-backed)
• OCR: Docling (IBM Granite) - Unified Markdown Pipeline
• Chunking: unified + remark (semantic chunking)
• Language: TypeScript 5.7 (strict mode)

• Database: PostgreSQL 16 (Row-Level Security)
• Vector DB: Qdrant 1.15 (1536 dimensions, HNSW)
• Cache/Queue: Redis 7 (BullMQ + cache)
• Storage: MinIO (dev) / Cloudflare R2 (prod)
• Reverse Proxy: Envoy (gRPC-Web transcoding + TLS)
• Monitoring: Prometheus + Grafana + Alertmanager
• Tracing: Jaeger + OpenTelemetry
• Logging: Loki + Promtail
• Orchestration: Docker Compose (dev & prod)

• LLM: Google Vertex AI - Gemini 2.5 Flash
• Embeddings: gemini-embedding-001 (1536 dimensions)
• OCR: Docling (IBM Granite)
• Code Interpreter: Gemini Tool Calling (natif)

apps/backend/src/
├── domain/              # Cœur métier (entities, use cases, schemas)
│   ├── entities/        # Business entities (immutable)
│   ├── usecases/        # Orchestration logique métier
│   └── schemas/         # Validation Zod
│
├── ports/               # Interfaces (contrats)
│   ├── primary/         # Inbound (gRPC handlers)
│   └── secondary/       # Outbound (repositories, providers)
│
├── adapters/            # Implémentations concrètes
│   ├── primary/         # gRPC service adapters
│   └── secondary/       # Prisma, Qdrant, Vertex AI, Redis
│
└── infrastructure/      # Configuration, DI, observability
    ├── di/              # InversifyJS container
    ├── grpc/            # Serveur + middlewares
    └── observability/   # Tracing, metrics, logging

• Singleton: Infrastructure (Prisma, Redis, Qdrant)
• RequestScope: Use cases (isolation par requête)
• Testabilité: Mocks faciles pour tous les adapters

Protocol Buffers → TypeScript Generated → Zod Validation → Prisma Types → Frontend Types

📘 Documentation Architecture: /docs/02-ARCHITECTURE/

La documentation complète (~150,000 mots, 57 fichiers) est disponible dans /docs:

• 📘 Sommaire Général - Point d'entrée de toute la doc
• 🚀 Démarrage Rapide - Guide complet d'installation
• 🏗️ Architecture Hexagonale - Principes et patterns
• 💬 Système RAG - Pipeline complet
• 📊 Cost Tracking - Système de quotas
• 🔍 Observabilité - Tracing, métriques, logs
• 🚨 Runbooks - Procédures incidents

Voir le guide détaillé: /docs/09-GUIDES-DÉVELOPPEUR/01-SETUP-ENVIRONNEMENT.md

Extensions requises:

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "prisma.prisma",
    "bradlc.vscode-tailwindcss",
    "ms-azuretools.vscode-docker",
    "rangav.vscode-thunder-client"
  ]
}

npm install              # Installer toutes dépendances
npm run dev             # Démarrer backend + frontend + worker
npm run build           # Build production (tous workspaces)
npm test                # Lancer tous les tests
npm run lint            # Linter tout le code
npm run format          # Formatter avec Prettier

cd apps/backend
npm run dev                    # Dev avec hot reload (nodemon)
npm run build                  # Build TypeScript
npm run start                  # Start production build
npm run db:migrate:dev         # Créer migration Prisma
npm run db:migrate:deploy      # Appliquer migrations
npm run db:generate            # Générer Prisma Client
npm run db:reset               # Reset DB (dev only!)
npm run proto:generate         # Générer types depuis proto files

cd apps/frontend
npm run dev                    # Dev avec hot reload
npm run build                  # Build production
npm run start                  # Start production build
npm run lint                   # ESLint
npm run type-check             # TypeScript check

cd apps/worker
npm run dev                    # Dev avec hot reload
npm run build                  # Build TypeScript
npm run start                  # Start production build

Voir: /docs/08-TESTS/

npm run test                   # Run all tests
npm run test:watch             # Watch mode
npm run test:coverage          # Coverage report

Targets de coverage:

• Use Cases: 90%+
• Adapters: 70%+
• Utils: 80%+

npm run test:integration       # Spin up containers + tests

Containers démarrés:

• PostgreSQL 16
• Redis 7
• Qdrant 1.15

npm run test:e2e               # Headless mode
npm run test:e2e:headed        # Voir le navigateur
npm run test:e2e:debug         # Debug mode

Navigateurs testés:

• Chromium
• Firefox
• WebKit (Safari)

npm run test:load              # Load test (1K users)
npm run test:stress            # Stress test (10K users)

npm run test:security          # Scan vulnérabilités

Voir: /docs/09-GUIDES-DÉVELOPPEUR/04-DEBUGGING.md

.vscode/launch.json:

{
  "configurations": [
    {
      "name": "Debug Backend",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "cwd": "${workspaceFolder}/apps/backend",
      "console": "integratedTerminal"
    }
  ]
}

# Lister les services
grpcurl -plaintext localhost:50051 list

# Tester un RPC
grpcurl -plaintext -d '{"conversationId":"123","message":"Hello"}' \
  localhost:50051 sophia.chat.v1.ChatService/StreamChat

# Prisma Studio (GUI)
npx prisma studio

# Logs de requêtes
DATABASE_LOG_LEVEL=debug npm run dev

# PostgreSQL CLI
docker compose exec postgres psql -U postgres -d sophia

Voir: /docs/09-GUIDES-DÉVELOPPEUR/02-CONVENTIONS-CODE.md

Highlights:

• Naming: camelCase (variables), PascalCase (classes), SCREAMING_SNAKE_CASE (constants)
• ESLint: Strict + Prettier
• Commits: Conventional Commits (feat, fix, refactor, docs, test, chore)
• Branches: <type>/<ticket-id>-<description> (ex: feat/123-add-rag-search)

# Démarrer infrastructure uniquement
docker compose up -d

# Services backend/frontend/worker sur host (hot reload rapide)
npm run dev

Pourquoi backend/frontend hors Docker en dev?

• ⚡ Hot reload 10x plus rapide
• 🐛 Debugging natif (pas de volumes lents)
• 🔧 Pas de rebuild image à chaque changement

Voir: DOCKER_GUIDE.md

# Build et démarrer TOUT le stack
docker compose -f docker-compose.prod.yml up -d

# Scaling horizontal
docker compose -f docker-compose.prod.yml up -d --scale backend=3 --scale worker=5

# Monitoring
docker compose ps
docker compose logs -f backend

Services en production:

• Backend (1-10 replicas)
• Worker (1-20 replicas)
• Frontend (SSR)
• PostgreSQL (avec persistent volume)
• Redis (avec AOF persistence)
• Qdrant (avec snapshots)
• MinIO (ou Cloudflare R2)
• Envoy Proxy (TLS + load balancing)
• Prometheus + Grafana + Jaeger + Loki

Voir: /docs/07-DÉPLOIEMENT/04-CI-CD-GITHUB-ACTIONS.md

Pipeline sur chaque PR:

1. Lint (ESLint + Prettier)
2. Type-check (TypeScript)
3. Tests unitaires (Vitest)
4. Tests d'intégration (Testcontainers)
5. Build (Docker images)
6. Security scan (Trivy)

Pipeline sur merge main:

1. Toutes les vérifications PR
2. Build production images
3. Deploy staging (auto)
4. Tests E2E sur staging
5. Approval manuel
6. Deploy production
7. Health checks
8. Notification Slack

Obligatoires:

• DATABASE_URL (PostgreSQL connection string)
• REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
• QDRANT_URL, QDRANT_API_KEY (⚠️ MANDATORY en prod)
• VERTEX_AI_PROJECT_ID, VERTEX_AI_LOCATION, GOOGLE_APPLICATION_CREDENTIALS
• BETTER_AUTH_SECRET, JWT_SECRET (min 32 chars)
• S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY (Cloudflare R2)

Optionnelles:

• NODE_ENV=production
• LOG_LEVEL=info
• WORKER_CONCURRENCY=10
• MAX_CONCURRENT_REQUESTS=100

Dashboards Grafana pré-configurés:

• API Performance (latency, throughput, errors)
• Cost Tracking (Vertex AI usage)
• Worker Health (queue depth, processing time)
• Infrastructure (CPU, RAM, disk)

Alertes Prometheus:

• High latency (p95 > 2s)
• High error rate (>5%)
• Service down
• Database unreachable
• Quota exceeded

Runbooks opérationnels:

• High Latency
• Service Down
• Database Unreachable
• High Error Rate
• Quota Exceeded

Voir: /docs/07-DÉPLOIEMENT/05-BACKUP-RESTORE.md

Stratégie 3-2-1:

• 3 copies (production + backup local + backup remote)
• 2 supports différents (disk + S3)
• 1 copie hors-site (Cloudflare R2)

Automatisation:

# Backup quotidien à 2h du matin
0 2 * * * /app/infrastructure/scripts/backup.sh

# Rétention: 30 jours

Restore:

./infrastructure/scripts/restore.sh backup-20250112-020000.sql.gz

Voir: /docs/12-ANNEXES/03-ROADMAP.md

• ✅ Chat conversationnel avec streaming
• ✅ RAG avec Qdrant
• ✅ Authentication (email/password + Google OAuth)
• ✅ Upload documents (PDF, DOCX, TXT)
• ✅ Cost tracking et quotas
• ✅ Multi-tenancy avec isolation stricte
• ✅ Observabilité complète (traces, metrics, logs)
• ✅ Documentation exhaustive (57 fichiers)

• Cache multi-niveaux (Redis + in-memory)
• Read replicas PostgreSQL
• Circuit breakers sur tous services externes
• Auto-scaling workers basé sur queue depth
• Dashboards Grafana avancés
• Rate limiting granulaire par endpoint
• Microsoft OAuth
• Magic link authentication

• Horizontal scaling backend (load balancer)
• Multi-region deployment (EU + US)
• Qdrant clustering (HA)
• CDN pour assets statiques
• Webhooks pour événements
• API publique (REST + gRPC)
• Export conversations (PDF, Markdown)
• Dark mode

• SSO (SAML, OIDC)
• RBAC (role-based access control)
• Audit logs complets
• SOC 2 Type II compliance
• Custom model fine-tuning
• On-premise deployment option
• White-label support
• Application mobile Flutter

Nous accueillons les contributions ! Merci de lire nos guidelines avant de contribuer.

1. Fork le projet
2. Créer une branche feature (git checkout -b feat/123-amazing-feature)
3. Commit vos changements (git commit -m 'feat: add amazing feature')
4. Push vers la branche (git push origin feat/123-amazing-feature)
5. Ouvrir une Pull Request

Voir: /docs/09-GUIDES-DÉVELOPPEUR/05-CONTRIBUTION.md

Checklist PR:

• Tests passent (npm test)
• Lint passe (npm run lint)
• Type-check passe (npm run type-check)
• Documentation mise à jour
• Commits suivent Conventional Commits
• Code review fait par 1+ reviewer

Nous nous engageons à maintenir un environnement accueillant et inclusif. Tout comportement inapproprié sera sanctionné.

Valeurs:

• Respect mutuel
• Collaboration constructive
• Feedback bienveillant
• Diversité et inclusion

Isolation stricte à tous les niveaux:

Voir: /docs/05-SÉCURITÉ/02-MULTI-TENANCY-ISOLATION.md

• Better Auth (moderne, type-safe, extensible)
• JWT avec JWKS rotation
• Sessions Redis-backed (7 jours)
• OAuth Google (Microsoft en Phase 2)
• Email verification obligatoire en production

Voir: /docs/05-SÉCURITÉ/01-AUTHENTIFICATION-AUTORISATION.md

Development:

• .env.local (git-ignored)
• Validation avec Zod au démarrage

Production (Docker Compose):

• Docker secrets ou encrypted env vars
• Jamais dans le code source
• Rotation régulière (30-90 jours)

Voir: /docs/05-SÉCURITÉ/03-SECRETS-MANAGEMENT.md

⚠️ NE PAS créer d'issue publique pour les vulnérabilités de sécurité.

Process:

1. Envoyer un email à: security@[entreprise].com
2. Inclure: Description, impact, étapes de reproduction
3. Attendre réponse (< 48h)
4. Coordinated disclosure après fix

Bug Bounty: Programme en cours de définition (Phase 4).

L'architecture de SophIA est conçue pour atteindre les objectifs suivants :

Note : Ces objectifs sont basés sur les patterns d'architecture implémentés. Des tests de charge en conditions réelles sont nécessaires pour valider ces métriques en production.

L'architecture intègre plusieurs optimisations :

1. Cache Redis → Réduction latence pour recherches répétées
2. Batch Embeddings → Optimisation coûts Vertex AI
3. DataLoader Pattern → Prévention N+1 queries
4. Connection Pooling → Gestion efficace connexions DB
5. Streaming Responses → Amélioration perception latence
6. Compression gzip → Optimisation bande passante
7. CDN (Phase 3) → Distribution assets statiques

Horizontal Scaling:

• Backend: 1-10 replicas (load balancer)
• Worker: 1-20 replicas (based on queue depth)
• PostgreSQL: Primary + 2 read replicas (Phase 2)

Resource Limits (par replica):

• Backend: 2 CPU, 4GB RAM
• Worker: 1 CPU, 2GB RAM
• PostgreSQL: 4 CPU, 8GB RAM
• Redis: 2 CPU, 4GB RAM
• Qdrant: 4 CPU, 8GB RAM

Copyright © 2025 [Nom de l'Entreprise]. All Rights Reserved.

Ce projet est propriétaire et confidentiel. Toute utilisation, copie, modification ou distribution non autorisée est strictement interdite.

Pour demandes de licence: legal@[entreprise].com

Ce projet utilise des bibliothèques open-source sous licences permissives (MIT, Apache 2.0, BSD).

Voir: /docs/12-ANNEXES/05-LICENCES.md

Attributions principales:

• Fastify (MIT)
• Next.js (MIT)
• Prisma (Apache 2.0)
• PostgreSQL (PostgreSQL License)
• Qdrant (Apache 2.0)

📘 Point d'entrée: /docs/00-SOMMAIRE-GÉNÉRAL.md

Guides rapides:

• 🚀 Démarrage Rapide
• ❓ FAQ Développeurs
• 🐛 Debugging
• 📖 Glossaire

🐛 GitHub Issues: github.com/[org]/sophia/issues

Avant de créer une issue:

1. Vérifier les issues existantes
2. Consulter la FAQ
3. Lire le guide de contribution

Template issue:

**Description:**
[Description claire du bug ou de la feature request]

**Steps to reproduce:**
1. ...
2. ...

**Expected behavior:**
...

**Actual behavior:**
...

**Environment:**
- OS: [e.g., macOS 14.1]
- Node.js: [e.g., 20.10.0]
- Docker: [e.g., 24.0.6]

💬 Slack/Discord: [À venir]

📧 Email: support@[entreprise].com

SLA Enterprise:

• Réponse: < 4h (heures ouvrées)
• Résolution critique: < 24h
• Dedicated Slack channel
• Hotline téléphonique