# wahib-elbessali/moroccan-regulatory-assistant architecture

> Architecture diagram of the GitHub repository wahib-elbessali/moroccan-regulatory-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wahib-elbessali/moroccan-regulatory-assistant
- Repository: https://github.com/wahib-elbessali/moroccan-regulatory-assistant

## Overview

The repository is a Moroccan regulatory RAG assistant: a user asks in Arabic, French, or Darija; the system searches access-filtered regulatory documents, orchestrates follow-up searches, and returns an answer with verified citations or an “unknown” result. The README also documents ingestion, identity and access, audit, live progress, local-model sovereignty, and optional leak-filtered web search. Several implementation areas are represented only by directories or documentation, so those relationships are shown only where the README supports them; sampled source confirms the Arabic normalizer and retrieval-store behavior.

Main entry points: [`src/api`](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/api) (API), [`src/retrieval`](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/retrieval) (Hybrid retrieval), [`src/agents/orchestrator`](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/agents/orchestrator) (Agent orchestration), [`src/ingestion`](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/ingestion) (Ingestion pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Identity and access"]
  node_api["API"]
  node_identity["Identity and rights"]
  node_audit[("Audit log")]
end

subgraph group_ingest["Document ingestion"]
  node_ingestion["Ingestion pipeline"]
  node_normalizer["Arabic normalizer<br/>[normalize.py]"]
  node_contracts["Shared contracts"]
end

subgraph group_search["Retrieval"]
  node_fake_retrieval["File retrieval fake<br/>[retrieval.py]"]
  node_retrieval["Hybrid retrieval"]
  node_qdrant_store[("Qdrant store<br/>[store.py]")]
end

subgraph group_answer["Answer orchestration"]
  node_orchestrator["Agent orchestration"]
  node_writer["Cited answer writer"]
  node_web_agent["Web agent"]
  node_interface["Chat and admin UI"]
end

subgraph group_sovereignty["Sovereignty"]
  node_local_models["Local models"]
  node_leak_filter["Leak protection"]
  node_web_search["Web search service"]
end

node_user(("Questioner"))

node_user -->|"asks"| node_api
node_api -->|"checks access"| node_identity
node_api -->|"submits question"| node_orchestrator
node_api -->|"records activity"| node_audit
node_orchestrator -->|"searches corpus"| node_retrieval
node_retrieval -->|"queries chunks"| node_qdrant_store
node_retrieval -->|"embeds and reranks"| node_local_models
node_retrieval -->|"filters by rights"| node_identity
node_orchestrator -->|"requests answer"| node_writer
node_writer -->|"returns cited answer"| node_orchestrator
node_orchestrator -.->|"may request web"| node_web_agent
node_web_agent -.->|"searches generic query"| node_web_search
node_web_agent -.->|"checks query"| node_leak_filter
node_api -->|"serves interaction"| node_interface
node_api -->|"accepts uploads"| node_ingestion
node_ingestion -->|"normalizes text"| node_normalizer
node_ingestion -->|"indexes chunks"| node_retrieval
node_ingestion -.->|"registers content"| node_leak_filter
node_ingestion -->|"uses shared models"| node_contracts
node_retrieval -->|"uses shared models"| node_contracts
node_fake_retrieval -->|"uses normalization"| node_normalizer
node_writer -.->|"uses local models"| node_local_models
node_orchestrator -->|"streams progress"| node_interface

click node_api "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/api"
click node_identity "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/core/db"
click node_audit "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/core/db"
click node_ingestion "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/ingestion"
click node_normalizer "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/blob/main/src/ingestion/normalize.py"
click node_contracts "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/core/contracts"
click node_fake_retrieval "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/blob/main/src/core/contracts/fakes/retrieval.py"
click node_retrieval "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/retrieval"
click node_qdrant_store "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/blob/main/src/retrieval/store.py"
click node_orchestrator "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/agents/orchestrator"
click node_writer "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/agents/answer"
click node_web_agent "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/agents/web"
click node_interface "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/ui"
click node_local_models "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/services/models"
click node_leak_filter "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/core/leak"
click node_web_search "https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/services/web-search"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_identity,node_audit toneBlue
class node_ingestion,node_normalizer,node_contracts toneAmber
class node_fake_retrieval,node_retrieval,node_qdrant_store toneMint
class node_orchestrator,node_writer,node_web_agent,node_interface toneRose
class node_local_models,node_leak_filter,node_web_search,node_user toneIndigo
```

## Components

### Identity and access

- [API](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/api): `src/api`
- [Identity and rights](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/core/db): `src/core/db`
- [Audit log](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/core/db): `src/core/db`

### Document ingestion

- [Ingestion pipeline](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/ingestion): `src/ingestion`
- [Arabic normalizer](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/blob/main/src/ingestion/normalize.py): `src/ingestion/normalize.py`
- [Shared contracts](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/core/contracts): `src/core/contracts`

### Retrieval

- [File retrieval fake](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/blob/main/src/core/contracts/fakes/retrieval.py): `src/core/contracts/fakes/retrieval.py`
- [Hybrid retrieval](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/retrieval): `src/retrieval`
- [Qdrant store](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/blob/main/src/retrieval/store.py): `src/retrieval/store.py`

### Answer orchestration

- [Agent orchestration](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/agents/orchestrator): `src/agents/orchestrator`
- [Cited answer writer](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/agents/answer): `src/agents/answer`
- [Web agent](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/agents/web): `src/agents/web`
- [Chat and admin UI](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/ui): `src/ui`

### Sovereignty

- [Local models](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/services/models): `services/models`
- [Leak protection](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/src/core/leak): `src/core/leak`
- [Web search service](https://github.com/wahib-elbessali/moroccan-regulatory-assistant/tree/main/services/web-search): `services/web-search`

### Other components

- **Questioner**

## Connections

- Questioner → API: asks (evidence: `README.md`)
- API → Identity and rights: checks access (evidence: `README.md`)
- API → Agent orchestration: submits question (evidence: `README.md`)
- API → Audit log: records activity (evidence: `README.md`)
- Agent orchestration → Hybrid retrieval: searches corpus (evidence: `README.md`)
- Hybrid retrieval → Qdrant store: queries chunks (evidence: `src/retrieval/store.py`)
- Hybrid retrieval → Local models: embeds and reranks (evidence: `src/retrieval/store.py`)
- Hybrid retrieval → Identity and rights: filters by rights (evidence: `src/retrieval/store.py`)
- Agent orchestration → Cited answer writer: requests answer (evidence: `README.md`)
- Cited answer writer → Agent orchestration: returns cited answer (evidence: `README.md`)
- Agent orchestration → Web agent: may request web (evidence: `README.md`)
- Web agent → Web search service: searches generic query (evidence: `README.md`)
- Web agent → Leak protection: checks query (evidence: `README.md`)
- API → Chat and admin UI: serves interaction (evidence: `README.md`)
- API → Ingestion pipeline: accepts uploads (evidence: `README.md`)
- Ingestion pipeline → Arabic normalizer: normalizes text (evidence: `src/ingestion/normalize.py`)
- Ingestion pipeline → Hybrid retrieval: indexes chunks (evidence: `README.md`)
- Ingestion pipeline → Leak protection: registers content
- Ingestion pipeline → Shared contracts: uses shared models (evidence: `src/core/contracts/protocols.py`)
- Hybrid retrieval → Shared contracts: uses shared models (evidence: `src/retrieval/store.py`)
- File retrieval fake → Arabic normalizer: uses normalization (evidence: `src/core/contracts/fakes/retrieval.py`)
- Cited answer writer → Local models: uses local models (evidence: `README.md`)
- Agent orchestration → Chat and admin UI: streams progress (evidence: `README.md`)