# hidekikzm/modulo-nlp--juribot architecture

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

- Interactive diagram: https://gitdiagram.com/hidekikzm/modulo-nlp--juribot
- Repository: https://github.com/hidekikzm/modulo-nlp--juribot

## Overview

Juribot is a Portuguese legal-question assistant: a user submits a query through the primary HTML UI or API, the API routes chat requests, optionally retrieves legal PDF passages from Qdrant, and returns cited sources or a Gemini-generated answer. Separate ingestion extracts/OCRs and chunks PDFs before embedding and publishing document versions. The graph follows the sampled API/runtime path; lexical search and the legacy RAG pipeline are present but not shown as wired into the active API.

Main entry points: [`backend/core/runtime.py`](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/core/runtime.py) (Runtime and search), [`backend/app_main.py`](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/app_main.py) (FastAPI app), [`backend/api/routers_chat.py`](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/api/routers_chat.py) (Chat endpoint), [`backend/rag/pipeline.py`](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/pipeline.py) (RAG pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and interaction"]
  node_ui["HTML chat UI<br/>[index.html]"]
  node_app["FastAPI app<br/>[app_main.py]"]
  node_chat["Chat endpoint<br/>[routers_chat.py]"]
  node_classify_api["Classification endpoint<br/>[routes_classify.py]"]
end

subgraph group_retrieval["Retrieval and generation"]
  node_router["RAG routing<br/>[router.py]"]
  node_embedding["Embedding model<br/>[embeddings.py]"]
  node_contract["Index contract<br/>[index_contract.py]"]
  node_gemini["Gemini generation"]
  node_lexical["Lexical search<br/>[lexical.py]"]
  node_legacy_pipeline["RAG pipeline<br/>[pipeline.py]"]
end

subgraph group_indexing["Document indexing"]
  node_pdfs["Legal PDFs"]
  node_ingest["PDF extraction and chunking<br/>[prepare_index.py]"]
  node_index_writer["Index publication<br/>[vector_qdrant.py]"]
end

subgraph group_resources["Runtime resources"]
  node_runtime["Runtime and search<br/>[runtime.py]"]
  node_config["Settings<br/>[config.py]"]
  node_qdrant[("Qdrant index")]
end

node_user(("User"))

node_user -->|"submits query"| node_ui
node_ui -.->|"calls API"| node_app
node_app -->|"mounts route"| node_chat
node_app -->|"mounts route"| node_classify_api
node_app -->|"loads resources"| node_runtime
node_app -->|"initializes"| node_router
node_chat -->|"decides mode"| node_router
node_chat -->|"searches sources"| node_runtime
node_runtime -->|"loads model"| node_embedding
node_runtime -->|"validates and searches"| node_contract
node_runtime -->|"queries index"| node_qdrant
node_chat -.->|"generates answer"| node_gemini
node_pdfs -->|"extracts text"| node_ingest
node_ingest -->|"embeds chunks"| node_embedding
node_ingest -->|"publishes versions"| node_index_writer
node_index_writer -->|"writes points"| node_qdrant
node_index_writer -->|"validates index"| node_contract
node_legacy_pipeline -.->|"imports only"| node_lexical
node_legacy_pipeline -->|"generates response"| node_gemini
node_legacy_pipeline -.->|"separate routing"| node_router
node_config -->|"configures resources"| node_runtime

click node_ui "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/ui/index.html"
click node_app "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/app_main.py"
click node_chat "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/api/routers_chat.py"
click node_classify_api "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/api/routes_classify.py"
click node_router "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/services/router.py"
click node_runtime "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/core/runtime.py"
click node_config "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/core/config.py"
click node_embedding "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/embeddings.py"
click node_contract "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/index_contract.py"
click node_gemini "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/generator_gemini.py"
click node_lexical "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/lexical.py"
click node_legacy_pipeline "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/pipeline.py"
click node_pdfs "https://github.com/hidekikzm/modulo-nlp--juribot/tree/main/data"
click node_ingest "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/ingest/prepare_index.py"
click node_index_writer "https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/vector_qdrant.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_ui,node_app,node_chat,node_classify_api,node_user toneBlue
class node_router,node_embedding,node_contract,node_gemini,node_lexical,node_legacy_pipeline toneAmber
class node_pdfs,node_ingest,node_index_writer toneMint
class node_runtime,node_config,node_qdrant toneRose
```

## Components

### API and interaction

- [HTML chat UI](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/ui/index.html): `backend/ui/index.html`
- [FastAPI app](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/app_main.py): `backend/app_main.py`
- [Chat endpoint](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/api/routers_chat.py): `backend/api/routers_chat.py`
- [Classification endpoint](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/api/routes_classify.py): `backend/api/routes_classify.py`

### Retrieval and generation

- [RAG routing](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/services/router.py): `backend/services/router.py`
- [Embedding model](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/embeddings.py): `backend/rag/embeddings.py`
- [Index contract](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/index_contract.py): `backend/rag/index_contract.py`
- [Gemini generation](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/generator_gemini.py): `backend/rag/generator_gemini.py`
- [Lexical search](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/lexical.py): `backend/rag/lexical.py`
- [RAG pipeline](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/pipeline.py): `backend/rag/pipeline.py`

### Document indexing

- [Legal PDFs](https://github.com/hidekikzm/modulo-nlp--juribot/tree/main/data): `data`
- [PDF extraction and chunking](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/ingest/prepare_index.py): `backend/ingest/prepare_index.py`
- [Index publication](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/rag/vector_qdrant.py): `backend/rag/vector_qdrant.py`

### Runtime resources

- [Runtime and search](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/core/runtime.py): `backend/core/runtime.py`
- [Settings](https://github.com/hidekikzm/modulo-nlp--juribot/blob/main/backend/core/config.py): `backend/core/config.py`
- **Qdrant index**

### Other components

- **User**

## Connections

- User → HTML chat UI: submits query (evidence: `README.md`)
- HTML chat UI → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Chat endpoint: mounts route (evidence: `backend/app_main.py`)
- FastAPI app → Classification endpoint: mounts route (evidence: `backend/app_main.py`)
- FastAPI app → Runtime and search: loads resources (evidence: `backend/app_main.py`)
- FastAPI app → RAG routing: initializes (evidence: `backend/app_main.py`)
- Chat endpoint → RAG routing: decides mode (evidence: `backend/api/routers_chat.py`)
- Chat endpoint → Runtime and search: searches sources (evidence: `backend/api/routers_chat.py`)
- Runtime and search → Embedding model: loads model (evidence: `backend/core/runtime.py`)
- Runtime and search → Index contract: validates and searches (evidence: `backend/core/runtime.py`)
- Runtime and search → Qdrant index: queries index (evidence: `backend/core/runtime.py`)
- Chat endpoint → Gemini generation: generates answer
- Legal PDFs → PDF extraction and chunking: extracts text (evidence: `README.md`)
- PDF extraction and chunking → Embedding model: embeds chunks (evidence: `backend/ingest/prepare_index.py`)
- PDF extraction and chunking → Index publication: publishes versions (evidence: `backend/ingest/prepare_index.py`)
- Index publication → Qdrant index: writes points (evidence: `backend/rag/vector_qdrant.py`)
- Index publication → Index contract: validates index (evidence: `backend/rag/vector_qdrant.py`)
- RAG pipeline → Lexical search: imports only
- RAG pipeline → Gemini generation: generates response (evidence: `backend/rag/pipeline.py`)
- RAG pipeline → RAG routing: separate routing
- Settings → Runtime and search: configures resources (evidence: `backend/core/runtime.py`)
