zakariae-boui/atlas-hcp-assistant

Architecture case study of ATLAS: a multilingual (AR/FR/EN/Darija) conversational assistant for Morocco's national statistics (HCP). Gemini NL-to-SQL over PostgreSQL with a ChromaDB RAG fallback and watchdog auto-ingestion. # ATLAS: a conversational assistant for Morocco's national statistics > Ask a question in Arabic, French, English, or Darija. Get back the number, the chart, and the sentence that explains it. Built during my Data Scientist internship at the Haut-Commissariat au Plan (HCP), regional directorate of Tanger-Tétouan-Al Hoceima. **About this repository.** ATLAS was built for and belongs to the HCP, so its source code is not published here. This repository is the **architecture case study**: the problem, the design, the decisions, and what the working system looks like. (The screenshots are from the real application.) ## The problem The HCP is Morocco's national statistics institution. Its data is public in principle, but in practice it lives in large, heterogeneous databases and hundreds of PDF publications, navigable only by people who already know the schema, the acronyms, and where to look. The internship brief: make that data reachable by a **non-expert asking a plain question in their own language**. That screenshot is the thesis of the project in one image: the conversation list includes a question asked in **Moroccan Darija** ("donne moi la population dyal..."), answered with the actual regional population figures. ## How it works Full walkthrough with the activity diagram in `docs/ARCHITECTURE.md`. The short version: ```mermaid flowchart LR U["User AR / FR / EN + voice"] --> FE["React frontend chat, dynamic charts, history"] FE --> BE["Flask backend auth, routing, orchestration"] BE --> LLM["Google Gemini intent analysis + NL to SQL"] LLM -->|SQL| PG[("PostgreSQL KPI tables")] LLM -->|fallback| RAG["ChromaDB RAG HCP publications + annual reports"] W["Watchdog monitor"] -->|"new indicator files"| PG PG --> BE RAG --> BE BE --> FE ``` 1. **Intent first.** The LLM's first job is routing: is this a data question, or conversation? Only data questions reach the SQL machinery. 2. **NL to SQL, grounded in the schema.** For data questions, Gemini generat …