Stack Technique

Cette page presente l'ensemble des technologies utilisees dans Bemba, organisees par composant.

Vue d'ensemble

┌─────────────────────────────────────────────────────────────────┐
│                         FRONTEND                                 │
│  React 18 + TypeScript + TailwindCSS + React Query              │
├─────────────────────────────────────────────────────────────────┤
│                       INTELLIGENCE ARTIFICIELLE                  │
│  Claude AI + Cohere Embeddings + Web Speech API                 │
├─────────────────────────────────────────────────────────────────┤
│                          BACKEND                                 │
│  Symfony 7 + PHP 8.3 + API Platform 3                           │
├─────────────────────────────────────────────────────────────────┤
│                      BASE DE DONNEES                             │
│  PostgreSQL 15 + PostGIS 3.4 + Redis 7                          │
├─────────────────────────────────────────────────────────────────┤
│                      INFRASTRUCTURE                              │
│  Docker + Traefik + Nginx + Loki + Sentry                       │
└─────────────────────────────────────────────────────────────────┘

Frontend

Framework Principal

Technologie	Version	Description
React	18.2	Bibliotheque JavaScript pour construire des interfaces utilisateur reactives
TypeScript	5.3	Superset de JavaScript avec typage statique pour une meilleure maintenabilite
React Router	6.21	Gestion du routage cote client (navigation SPA)

Styling & UI

Technologie	Version	Description
TailwindCSS	3.4	Framework CSS utility-first pour un styling rapide et coherent
Headless UI	1.7	Composants UI accessibles et non-styles (modals, dropdowns, tabs)
Heroicons	2.1	Collection d'icones SVG par les createurs de Tailwind
clsx	2.1	Utilitaire pour construire des classes CSS conditionnelles

Gestion d'Etat & Donnees

Technologie	Version	Description
TanStack Query	5.17	Gestion du cache et des requetes API (anciennement React Query)
Zustand	4.5	Gestion d'etat global legere et simple
React Hook Form	7.49	Gestion performante des formulaires avec validation
Axios	1.13	Client HTTP pour les appels API

Tableaux & Visualisation

Technologie	Version	Description
TanStack Table	8.11	Tableaux headless avec tri, filtrage, pagination
Chart.js	4.4	Graphiques interactifs (barres, lignes, camemberts)
React-Chartjs-2	5.2	Wrapper React pour Chart.js
Recharts	2.10	Bibliotheque de graphiques basee sur D3
Mermaid	11.12	Generation de diagrammes a partir de texte

Cartographie (SIG)

Technologie	Version	Description
Leaflet	1.9	Bibliotheque de cartographie interactive open source
React-Leaflet	4.2	Composants React pour Leaflet
Leaflet.heat	0.2	Plugin pour les cartes de chaleur (heatmaps)
React-Leaflet-Cluster	4.0	Clustering de marqueurs pour grandes quantites de points
Turf.js	7.3	Analyse geospatiale cote client
React-Globe.gl	2.37	Visualisation 3D du globe terrestre

Export & Documents

Technologie	Version	Description
ExcelJS	4.4	Generation de fichiers Excel (.xlsx) cote client
jsPDF	4.1	Generation de documents PDF cote client
jspdf-autotable	5.0	Plugin jsPDF pour tableaux automatiques
html2canvas	1.4	Capture de screenshots de composants HTML
FileSaver	2.0	Sauvegarde de fichiers generes cote client

Internationalisation

Technologie	Version	Description
i18next	23.16	Framework d'internationalisation complet
react-i18next	14.1	Integration React pour i18next
i18next-browser-languagedetector	7.2	Detection automatique de la langue du navigateur

Autres

Technologie	Version	Description
date-fns	3.3	Manipulation de dates (alternative legere a Moment.js)
React Hot Toast	2.4	Notifications toast elegantes
React Dropzone	15.0	Zone de drop pour upload de fichiers
dnd-kit	6.3	Drag and drop accessible
React Markdown	10.1	Rendu de contenu Markdown
React Grid Layout	2.2	Layouts redimensionnables et draggables

Monitoring Frontend

Technologie	Version	Description
Sentry React	10.42	Suivi des erreurs et performances frontend

Backend

Framework Principal

Technologie	Version	Description
PHP	8.3	Langage de programmation backend
Symfony	7.1	Framework PHP moderne et modulaire
API Platform	3.2	Framework pour creer des APIs REST/GraphQL

Base de Donnees

Technologie	Version	Description
Doctrine ORM	3.0	Object-Relational Mapping pour PHP
Doctrine Migrations	3.3	Gestion des migrations de schema de base de donnees
Ramsey UUID Doctrine	2.0	Support des UUID comme identifiants

Authentification & Securite

Technologie	Version	Description
LexikJWT	2.20	Authentification par JSON Web Tokens
Gesdinet JWT Refresh Token	1.5	Gestion des refresh tokens JWT
Symfony Security	7.1	Systeme de securite (voters, firewalls, authentification)
Symfony Rate Limiter	7.1	Protection contre les attaques par force brute
OTPHP	11.4	Generation de codes OTP (authentification 2FA)

Communication & API

Technologie	Version	Description
Nelmio CORS	2.4	Gestion des headers CORS pour l'API
Guzzle	7.8	Client HTTP pour appels vers services externes
Symfony Mailer	7.1	Envoi d'emails (SMTP, API)
Symfony Messenger	7.1	File de messages asynchrones

Generation de Documents

Technologie	Version	Description
PhpSpreadsheet	2.0	Generation de fichiers Excel (.xlsx)
PhpWord	1.4	Generation de fichiers Word (.docx)
DomPDF	3.1	Generation de PDF a partir de HTML
Endroid QR Code	5.0	Generation de codes QR

Planification & Taches

Technologie	Version	Description
Symfony Scheduler	7.1	Planification de taches recurrentes (cron)
Cron Expression	3.3	Parsing d'expressions cron
Symfony Lock	7.1	Mecanismes de verrouillage pour taches concurrentes

Monitoring Backend

Technologie	Version	Description
Sentry Symfony	5.9	Suivi des erreurs et performances backend
Symfony Monolog	3.10	Logging structure

Tests & Qualite

Technologie	Version	Description
PHPUnit	10.5	Framework de tests unitaires et fonctionnels
PHPStan	latest	Analyse statique du code PHP
PHPStan Doctrine	latest	Plugin PHPStan pour Doctrine
PHPStan Symfony	latest	Plugin PHPStan pour Symfony

Base de Donnees

Technologie	Version	Description
PostgreSQL	15	Base de donnees relationnelle performante et fiable
PostGIS	3.4	Extension PostgreSQL pour donnees geospatiales
Redis	7	Cache en memoire pour sessions, cache applicatif

Pourquoi PostgreSQL + PostGIS ?

Donnees geographiques : Stockage natif de geometries (points, polygones)
Requetes spatiales : Distance, intersection, contenance
Index spatiaux : Performances optimisees sur les donnees geo
Conformite OGC : Standards ouverts de l'industrie SIG

Infrastructure

Conteneurisation et réseau

Technologie	Version	Description
Docker Engine	24+ (natif, Ubuntu)	Conteneurs, sur des VPS OVH
Docker Compose	v2 (`docker compose`, toujours avec `-f`)	Un fichier par environnement (`docker-compose.prod.yml`, `docker-compose.preprod.yml`)
Traefik	2.10	Reverse proxy, HTTPS Let's Encrypt, routage par nom d'hôte
Nginx	alpine	Fichiers statiques du frontend et de la documentation ; devant PHP-FPM dans le conteneur backend
PHP-FPM	8.3 (image `php:8.3-fpm-alpine`)	Exécution de Symfony
supervisord	—	Lance Nginx, PHP-FPM et les workers Messenger dans le conteneur backend

Images Docker utilisées

Image	Usage
`traefik:v2.10`	Reverse proxy et certificats
`nginx:alpine`	Frontend et documentation
image construite depuis `backend/Dockerfile.prod`	Backend (PHP-FPM + Nginx + workers)
`postgis/postgis:15-3.4-alpine`	PostgreSQL + PostGIS
`redis:7-alpine`	Cache
`grafana/loki:2.9.0`, `grafana/promtail:2.9.0`	Journaux
`gcr.io/cadvisor/cadvisor`, `prom/node-exporter`, `prometheuscommunity/postgres-exporter`, `oliver006/redis_exporter`	Métriques (ports liés à 127.0.0.1)
`boky/postfix`	Relais SMTP de la production, réservé au KoboToolbox de la préproduction

Monitoring & Observabilité

Technologie	Où	Description
Loki + Promtail	serveur de production	Journaux de tous les conteneurs, rétention un an, copie hors site
Exporteurs Prometheus	serveur de production (127.0.0.1)	Métriques des conteneurs, du système, de PostgreSQL et de Redis
Prometheus + Grafana	poste d'administration (`monitoring/`)	Tableaux de bord, via des tunnels SSH
Sentry	service externe	Erreurs du frontend et du backend

Voir Monitoring et Logs.

Intelligence Artificielle (assistant Bemba)

Assistant conversationnel

Technologie	Modèle	Description
Claude (Anthropic)	`claude-opus-5` par défaut (paramètre `claude_model`, variable `CLAUDE_MODEL`)	Compréhension des questions et rédaction des réponses

Principe : le modèle n'écrit jamais de SQL. Il appelle des outils typés (backend/src/Service/Assistant/Outil/) qui appliquent eux-mêmes le cloisonnement, le filtre géographique et les permissions de l'utilisateur :

Outil	Rôle
Statistiques, couverture, suivi-évaluation	Chiffres agrégés dans le périmètre de l'utilisateur
Recherche, détail d'un ménage	Données nominatives, si les droits le permettent
Référentiel géographique, localiser	Régions, secteurs, localités, carte
Naviguer	Ouvrir un écran de l'application
Déposer une plainte	Enregistrement guidé d'une réclamation
Rechercher dans les connaissances	Base documentaire (voir ci-dessous)

Langues : français, portugais, anglais, kriol (créole de Guinée-Bissau, réservé à l'assistant).
Limites : 40 questions par tranche de 10 minutes et par utilisateur ; un tour dure au plus 50 secondes.
Assistant du site public : point d'entrée anonyme séparé, trois outils sans accès aux données (présentation du projet, pages publiées, dépôt de réclamation), limité par adresse IP.
Contrat d'API et ajout d'un outil : docs/ASSISTANT_IA.md du dépôt.

Base documentaire (RAG)

Élément	Description
Sources	Build de ce site de documentation (fr, pt, en) et articles publiés de la base de connaissances
Index	Table `assistant_documents` : recherche plein texte PostgreSQL (`unaccent`, configurations française, portugaise, anglaise)
Repli sémantique	Embeddings Cohere `embed-multilingual-v3.0`, utilisés seulement quand le plein texte ne trouve rien
Mise à jour	`php bin/console app:assistant:indexer` après chaque déploiement de la documentation et chaque nuit (cron 03:15)

Similarité des plaintes

Algorithme	Usage
Embeddings Cohere	Regroupement des plaintes similaires (seuil 0,75)
TF-IDF	Repli sans clé Cohere (seuil 0,45)
Levenshtein, similar_text	Doublons de noms (ménages, plaignants)
Haversine	Distance entre coordonnées GPS

Voix

La saisie et la lecture vocales utilisent la Web Speech API du navigateur (gratuite, sans service externe) : fr-FR, pt-PT, en-US ; le kriol utilise la voix portugaise.

Stockage des Embeddings

Les embeddings sont stockes directement dans PostgreSQL :

Champ	Type	Description
`embedding`	JSON	Vecteur d'embedding Cohere (1024 dimensions)
`cluster_id`	UUID	Cluster associe
`cluster_similarity_score`	FLOAT	Score de similarite avec le cluster
`centroid_embedding`	JSON	Embedding centre du cluster
`keywords`	JSON	Mots-cles extraits

Interface utilisateur

L'assistant est un composant unique (components/assistant/AssistantChat.tsx), monté par un widget flottant sur toutes les pages sauf la carte, et par le panneau de la carte.

Documentation

Technologie	Version	Description
Docusaurus	3.10	Generateur de sites de documentation
MDX	3.0	Markdown avec composants React
Prism React Renderer	2.3	Coloration syntaxique du code

Outils de Developpement

Frontend

Outil	Description
Create React App	Boilerplate et configuration Webpack
ESLint	Linter JavaScript/TypeScript
PostCSS	Transformations CSS (autoprefixer)
Jest	Framework de tests
Testing Library	Tests de composants React

Backend

Outil	Description
Symfony CLI	Outils de developpement Symfony
Composer	Gestionnaire de dependances PHP
Symfony Maker	Generation de code (entites, controllers)

Integrations Externes

Services IA

Service	Description
Anthropic (Claude)	Assistant Bemba (clé `ANTHROPIC_API_KEY`)
Cohere	Embeddings multilingues (clé `COHERE_API_KEY`), facultatif

Collecte de Donnees

Service	Description
KoBoToolbox	Collecte de donnees terrain (formulaires)
Survey Solutions	Collecte de donnees (CAPI/CAWI)

Paiements & Communication

Service	Description
Opérateurs de paiement (Orange Money, MTN, Wave, TELECEL)	Échange de fichiers (ST envoyé à l'opérateur, CT reçu pour la réconciliation) ; aucune API connectée
SMTP OVH	E-mails transactionnels depuis `noreply@ucp-pch.org`, envoyés de façon asynchrone
Passerelle SMS	Campagnes SMS

Choix Architecturaux

Pourquoi cette stack ?

Choix	Justification
React + TypeScript	Typage statique, maintenabilite, large ecosysteme
Symfony + API Platform	Framework mature, securise, API-first
PostgreSQL + PostGIS	Donnees geographiques natives, performances
TanStack Query	Cache intelligent, synchronisation automatique
TailwindCSS	Styling rapide, design system coherent
Docker	Environnements reproductibles, deploiement simplifie
Claude AI	LLM performant, contexte long, support multilingue
Cohere Embeddings	Embeddings multilingues 100+ langues, ideal pour l'Afrique
Web Speech API	Reconnaissance vocale native, gratuite, sans dependance externe

Principes

API-First : Le backend expose une API REST complete
Type-Safe : TypeScript partout cote frontend
Stateless : JWT pour l'authentification (pas de sessions serveur)
Containerise : Tous les services dans Docker
Observable : Monitoring complet (metriques, logs, traces)
IA-Augmente : Assistant intelligent pour simplifier l'acces aux donnees
Multilingue : Support natif de 4 langues incluant le Kriol

Versions Minimales Requises

Composant	Version Minimale
Node.js	20.x
PHP	8.3
PostgreSQL	15
Docker	24
Docker Compose	2.x

Vue d'ensemble​

Frontend​

Framework Principal​

Styling & UI​

Gestion d'Etat & Donnees​

Tableaux & Visualisation​

Cartographie (SIG)​

Export & Documents​

Internationalisation​

Autres​

Monitoring Frontend​

Backend​

Framework Principal​

Base de Donnees​

Authentification & Securite​

Communication & API​

Generation de Documents​

Planification & Taches​

Monitoring Backend​

Tests & Qualite​

Base de Donnees​

Pourquoi PostgreSQL + PostGIS ?​

Infrastructure​

Conteneurisation et réseau​

Images Docker utilisées​

Monitoring & Observabilité​

Intelligence Artificielle (assistant Bemba)​

Assistant conversationnel​

Base documentaire (RAG)​

Similarité des plaintes​

Voix​

Stockage des Embeddings​

Interface utilisateur​

Documentation​

Outils de Developpement​

Frontend​

Backend​

Integrations Externes​

Services IA​

Collecte de Donnees​

Paiements & Communication​

Choix Architecturaux​

Pourquoi cette stack ?​

Principes​

Versions Minimales Requises​

Prochaines etapes​

Vue d'ensemble

Frontend

Framework Principal

Styling & UI

Gestion d'Etat & Donnees

Tableaux & Visualisation

Cartographie (SIG)

Export & Documents

Internationalisation

Autres

Monitoring Frontend

Backend

Framework Principal

Base de Donnees

Authentification & Securite

Communication & API

Generation de Documents

Planification & Taches

Monitoring Backend

Tests & Qualite

Base de Donnees

Pourquoi PostgreSQL + PostGIS ?

Infrastructure

Conteneurisation et réseau

Images Docker utilisées

Monitoring & Observabilité

Intelligence Artificielle (assistant Bemba)

Assistant conversationnel

Base documentaire (RAG)

Similarité des plaintes

Voix

Stockage des Embeddings

Interface utilisateur

Documentation

Outils de Developpement

Frontend

Backend

Integrations Externes

Services IA

Collecte de Donnees

Paiements & Communication

Choix Architecturaux

Pourquoi cette stack ?

Principes

Versions Minimales Requises

Prochaines etapes