# 2501pr0ject/traboule architecture

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

- Interactive diagram: https://gitdiagram.com/2501pr0ject/traboule
- Repository: https://github.com/2501pr0ject/traboule

## Overview

Traboule is a local-first territorial-intelligence engine for answering questions about Lyon Métropole establishments, PLU-H zoning, and written planning rules, with sourced, time-anchored answers and explicit abstention. Its documented workflow combines establishment data, spatially associates locations with zones, and relates zones to rule passages; document extraction and indexing support the rule-retrieval branch. The tree also contains ingestion, geographic reference, and evaluation stages. No query-serving implementation is shown in the sampled files, so the graph does not invent a runtime request pipeline; some documented capabilities are represented as subsystems without asserted call edges.

Main entry points: [`packages/traboule/config.py`](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/config.py) (Project configuration), [`packages/traboule/contracts/question.py`](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/contracts/question.py) (Question contract), [`packages/traboule/contracts/passage.py`](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/contracts/passage.py) (Passage contract), [`packages/traboule/ingestion/database.py`](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/ingestion/database.py) (Local data build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data ingestion"]
  node_download["Source downloads<br/>[download.py]"]
  node_sirene["Sirene processing<br/>[sirene.py]"]
  node_catalogue["Data catalogue<br/>[catalogue.py]"]
  node_database["Local data build<br/>[database.py]"]
  node_store[("DuckDB datasets")]
end

subgraph group_geo["Geographic analysis"]
  node_referentiel["Geo reference<br/>[referentiel.py]"]
  node_spatial["Zone association<br/>[jointure.py]"]
  node_confidence["Zone confidence<br/>[confiance.py]"]
  node_minorant["Count minorants<br/>[minorant.py]"]
  node_zone_rules["Zone-rule mapping<br/>[zones_reglement.py]"]
end

subgraph group_docs["Rule documents"]
  node_reglement["Regulation parsing<br/>[reglement.py]"]
  node_cahiers["Cahier parsing<br/>[cahiers.py]"]
  node_extract["PDF extraction<br/>[extraction.py]"]
  node_segment["Passage splitting<br/>[decoupage.py]"]
  node_index["Vector index<br/>[index.py]"]
end

subgraph group_contracts["Contracts and evaluation"]
  node_question["Question contract<br/>[question.py]"]
  node_answer["Sourced response<br/>[reponse.py]"]
  node_passage["Passage contract<br/>[passage.py]"]
  node_sampling["Confidence review<br/>[tirage.py]"]
  node_config["Project configuration<br/>[config.py]"]
end

node_analyst(("Questioner"))

node_analyst -.->|"asks"| node_question
node_question -.->|"answered by"| node_answer
node_download -->|"reads settings"| node_config
node_sirene -->|"reads settings"| node_config
node_database -->|"documents tables"| node_catalogue
node_database -->|"builds"| node_store
node_spatial -->|"uses confidence"| node_confidence
node_spatial -->|"reads thresholds"| node_config
node_minorant -->|"reads thresholds"| node_config
node_reglement -->|"maps zone codes"| node_zone_rules
node_reglement -->|"builds passages"| node_passage
node_cahiers -->|"builds passages"| node_passage
node_index -->|"indexes passages"| node_passage
node_index -->|"uses zone metadata"| node_zone_rules
node_answer -->|"uses route"| node_question
node_sampling -->|"reads settings"| node_config

click node_download "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/ingestion/download.py"
click node_sirene "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/ingestion/sirene.py"
click node_catalogue "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/catalogue.py"
click node_database "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/ingestion/database.py"
click node_referentiel "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/geo/referentiel.py"
click node_spatial "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/geo/jointure.py"
click node_confidence "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/geo/confiance.py"
click node_minorant "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/geo/minorant.py"
click node_zone_rules "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/geo/zones_reglement.py"
click node_reglement "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/retrieval/reglement.py"
click node_cahiers "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/retrieval/cahiers.py"
click node_extract "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/retrieval/extraction.py"
click node_segment "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/retrieval/decoupage.py"
click node_index "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/retrieval/index.py"
click node_question "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/contracts/question.py"
click node_answer "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/contracts/reponse.py"
click node_passage "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/contracts/passage.py"
click node_sampling "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/evaluation/tirage.py"
click node_config "https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/config.py"

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_download,node_sirene,node_catalogue,node_database,node_store toneBlue
class node_referentiel,node_spatial,node_confidence,node_minorant,node_zone_rules toneAmber
class node_reglement,node_cahiers,node_extract,node_segment,node_index toneMint
class node_question,node_answer,node_passage,node_sampling,node_config toneRose
class node_analyst toneIndigo
```

## Components

### Data ingestion

- [Source downloads](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/ingestion/download.py): `packages/traboule/ingestion/download.py`
- [Sirene processing](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/ingestion/sirene.py): `packages/traboule/ingestion/sirene.py`
- [Data catalogue](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/catalogue.py): `packages/traboule/catalogue.py`
- [Local data build](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/ingestion/database.py): `packages/traboule/ingestion/database.py`
- **DuckDB datasets**

### Geographic analysis

- [Geo reference](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/geo/referentiel.py): `packages/traboule/geo/referentiel.py`
- [Zone association](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/geo/jointure.py): `packages/traboule/geo/jointure.py`
- [Zone confidence](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/geo/confiance.py): `packages/traboule/geo/confiance.py`
- [Count minorants](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/geo/minorant.py): `packages/traboule/geo/minorant.py`
- [Zone-rule mapping](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/geo/zones_reglement.py): `packages/traboule/geo/zones_reglement.py`

### Rule documents

- [Regulation parsing](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/retrieval/reglement.py): `packages/traboule/retrieval/reglement.py`
- [Cahier parsing](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/retrieval/cahiers.py): `packages/traboule/retrieval/cahiers.py`
- [PDF extraction](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/retrieval/extraction.py): `packages/traboule/retrieval/extraction.py`
- [Passage splitting](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/retrieval/decoupage.py): `packages/traboule/retrieval/decoupage.py`
- [Vector index](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/retrieval/index.py): `packages/traboule/retrieval/index.py`

### Contracts and evaluation

- [Question contract](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/contracts/question.py): `packages/traboule/contracts/question.py`
- [Sourced response](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/contracts/reponse.py): `packages/traboule/contracts/reponse.py`
- [Passage contract](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/contracts/passage.py): `packages/traboule/contracts/passage.py`
- [Confidence review](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/evaluation/tirage.py): `packages/traboule/evaluation/tirage.py`
- [Project configuration](https://github.com/2501pr0ject/traboule/blob/main/packages/traboule/config.py): `packages/traboule/config.py`

### Other components

- **Questioner**

## Connections

- Questioner → Question contract: asks (evidence: `README.md`)
- Question contract → Sourced response: answered by (evidence: `README.md`)
- Source downloads → Project configuration: reads settings (evidence: `packages/traboule/ingestion/download.py`)
- Sirene processing → Project configuration: reads settings (evidence: `packages/traboule/ingestion/sirene.py`)
- Local data build → Data catalogue: documents tables (evidence: `packages/traboule/ingestion/database.py`)
- Local data build → DuckDB datasets: builds (evidence: `packages/traboule/ingestion/database.py`)
- Zone association → Zone confidence: uses confidence (evidence: `packages/traboule/geo/jointure.py`)
- Zone association → Project configuration: reads thresholds (evidence: `packages/traboule/geo/jointure.py`)
- Count minorants → Project configuration: reads thresholds (evidence: `packages/traboule/geo/minorant.py`)
- Regulation parsing → Zone-rule mapping: maps zone codes (evidence: `packages/traboule/retrieval/reglement.py`)
- Regulation parsing → Passage contract: builds passages (evidence: `packages/traboule/retrieval/reglement.py`)
- Cahier parsing → Passage contract: builds passages (evidence: `packages/traboule/retrieval/cahiers.py`)
- Vector index → Passage contract: indexes passages (evidence: `packages/traboule/retrieval/index.py`)
- Vector index → Zone-rule mapping: uses zone metadata (evidence: `packages/traboule/retrieval/index.py`)
- Sourced response → Question contract: uses route (evidence: `packages/traboule/contracts/reponse.py`)
- Confidence review → Project configuration: reads settings (evidence: `packages/traboule/evaluation/tirage.py`)
