# peramee/regulatory-rag-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/peramee/regulatory-rag-assistant
- Repository: https://github.com/peramee/regulatory-rag-assistant

## Overview

Regulatory RAG Assistant accepts regulatory documents and questions, indexes document passages, retrieves relevant evidence, and returns grounded answers with validated citations or an insufficient-evidence refusal. The primary workflow runs through the Streamlit client, FastAPI, and RAG service; ingestion and question answering are distinct stages. The README also documents API-driven evaluation and structured operational logging. Source excerpts are partial, so uncertain internal route wiring is omitted; documented capabilities and the tree support the broader subsystem paths shown.

Main entry points: [`src/regulatory_rag/service.py`](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/service.py) (RAG service), [`src/regulatory_rag/api.py`](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/api.py) (FastAPI), [`src/regulatory_rag/retrieval.py`](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/retrieval.py) (Retriever), [`scripts/evaluate_api.py`](https://github.com/peramee/regulatory-rag-assistant/blob/main/scripts/evaluate_api.py) (Evaluation client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["User interface"]
  node_ui["Streamlit UI<br/>[streamlit_app.py]"]
  node_client["HTTP client<br/>[api_client.py]"]
end

subgraph group_api["API and orchestration"]
  node_api_service["FastAPI<br/>[api.py]"]
  node_rag_service["RAG service<br/>[service.py]"]
  node_models["Typed schemas<br/>[models.py]"]
end

subgraph group_documents["Document ingestion"]
  node_ingestion["Extract and chunk<br/>[ingestion.py]"]
end

subgraph group_rag["Retrieval and generation"]
  node_retriever["Retriever<br/>[retrieval.py]"]
  node_embeddings["Embedding adapter<br/>[providers.py]"]
  node_store[("Chroma index<br/>[store.py]")]
  node_generation["Grounding and citations<br/>[generation.py]"]
  node_llm_adapter["Chat adapter<br/>[providers.py]"]
end

subgraph group_operations["Evaluation and observability"]
  node_observability["Structured logging<br/>[observability.py]"]
  node_evaluation_runner["Evaluation client<br/>[evaluate_api.py]"]
  node_evaluation["Evaluation metrics<br/>[evaluation.py]"]
  node_dataset["Evaluation cases<br/>[dataset.json]"]
end

node_browser(("User"))
node_embedding_api{{"Embedding service"}}
node_llm_api{{"Chat service"}}
node_evaluation_api{{"Evaluation API"}}

node_browser -->|"asks"| node_ui
node_ui -->|"submits question"| node_client
node_client -->|"POST /query"| node_api_service
node_api_service -->|"handles request"| node_rag_service
node_rag_service -->|"searches"| node_retriever
node_retriever -->|"embeds text"| node_embeddings
node_embeddings -->|"requests vectors"| node_embedding_api
node_retriever -->|"queries index"| node_store
node_store -->|"returns passages"| node_retriever
node_rag_service -->|"builds and validates"| node_generation
node_rag_service -->|"requests completion"| node_llm_adapter
node_llm_adapter -->|"sends prompt"| node_llm_api
node_rag_service -->|"emits lifecycle logs"| node_observability
node_ui -->|"displays response"| node_api_service
node_api_service -->|"validates requests"| node_models
node_api_service -->|"indexes documents"| node_ingestion
node_rag_service -->|"extracts and chunks"| node_ingestion
node_retriever -->|"writes vectors"| node_store
node_evaluation_runner -->|"loads cases"| node_dataset
node_evaluation_runner -->|"submits cases"| node_evaluation_api
node_evaluation_api -->|"queries same API"| node_api_service
node_evaluation_runner -->|"evaluates results"| node_evaluation
node_evaluation -->|"checks responses"| node_models

click node_ui "https://github.com/peramee/regulatory-rag-assistant/blob/main/streamlit_app.py"
click node_client "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/api_client.py"
click node_api_service "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/api.py"
click node_rag_service "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/service.py"
click node_ingestion "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/ingestion.py"
click node_retriever "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/retrieval.py"
click node_embeddings "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/providers.py"
click node_store "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/store.py"
click node_generation "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/generation.py"
click node_llm_adapter "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/providers.py"
click node_models "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/models.py"
click node_observability "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/observability.py"
click node_evaluation_runner "https://github.com/peramee/regulatory-rag-assistant/blob/main/scripts/evaluate_api.py"
click node_evaluation "https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/evaluation.py"
click node_dataset "https://github.com/peramee/regulatory-rag-assistant/blob/main/evaluation/dataset.json"

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_client,node_browser toneBlue
class node_api_service,node_rag_service,node_models toneAmber
class node_ingestion,node_evaluation_api toneMint
class node_retriever,node_embeddings,node_store,node_generation,node_llm_adapter toneRose
class node_observability,node_evaluation_runner,node_evaluation,node_dataset,node_embedding_api,node_llm_api toneIndigo
```

## Components

### User interface

- [Streamlit UI](https://github.com/peramee/regulatory-rag-assistant/blob/main/streamlit_app.py): `streamlit_app.py`
- [HTTP client](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/api_client.py): `src/regulatory_rag/api_client.py`

### API and orchestration

- [FastAPI](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/api.py): `src/regulatory_rag/api.py`
- [RAG service](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/service.py): `src/regulatory_rag/service.py`
- [Typed schemas](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/models.py): `src/regulatory_rag/models.py`

### Document ingestion

- [Extract and chunk](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/ingestion.py): `src/regulatory_rag/ingestion.py`

### Retrieval and generation

- [Retriever](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/retrieval.py): `src/regulatory_rag/retrieval.py`
- [Embedding adapter](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/providers.py): `src/regulatory_rag/providers.py`
- [Chroma index](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/store.py): `src/regulatory_rag/store.py`
- [Grounding and citations](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/generation.py): `src/regulatory_rag/generation.py`
- [Chat adapter](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/providers.py): `src/regulatory_rag/providers.py`

### Evaluation and observability

- [Structured logging](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/observability.py): `src/regulatory_rag/observability.py`
- [Evaluation client](https://github.com/peramee/regulatory-rag-assistant/blob/main/scripts/evaluate_api.py): `scripts/evaluate_api.py`
- [Evaluation metrics](https://github.com/peramee/regulatory-rag-assistant/blob/main/src/regulatory_rag/evaluation.py): `src/regulatory_rag/evaluation.py`
- [Evaluation cases](https://github.com/peramee/regulatory-rag-assistant/blob/main/evaluation/dataset.json): `evaluation/dataset.json`

### Other components

- **User**
- **Embedding service**
- **Chat service**
- **Evaluation API**

## Connections

- User → Streamlit UI: asks
- Streamlit UI → HTTP client: submits question
- HTTP client → FastAPI: POST /query
- FastAPI → RAG service: handles request
- RAG service → Retriever: searches
- Retriever → Embedding adapter: embeds text
- Embedding adapter → Embedding service: requests vectors
- Retriever → Chroma index: queries index
- Chroma index → Retriever: returns passages
- RAG service → Grounding and citations: builds and validates
- RAG service → Chat adapter: requests completion
- Chat adapter → Chat service: sends prompt
- RAG service → Structured logging: emits lifecycle logs
- Streamlit UI → FastAPI: displays response
- FastAPI → Typed schemas: validates requests
- FastAPI → Extract and chunk: indexes documents
- RAG service → Extract and chunk: extracts and chunks
- Retriever → Chroma index: writes vectors
- Evaluation client → Evaluation cases: loads cases
- Evaluation client → Evaluation API: submits cases
- Evaluation API → FastAPI: queries same API
- Evaluation client → Evaluation metrics: evaluates results
- Evaluation metrics → Typed schemas: checks responses