# shuiii129/agora-rag-ml-assessment architecture

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

- Interactive diagram: https://gitdiagram.com/shuiii129/agora-rag-ml-assessment
- Repository: https://github.com/shuiii129/agora-rag-ml-assessment

## Overview

This is a local RAG application for asking grounded questions about AI-governance documents, through either a web chat or the CLI. The query path embeds a question, retrieves relevant chunks from ChromaDB, and asks Gemini to produce a grounded answer with source references. A separate ingestion path reads document text and CSV metadata, cleans and chunks the text, embeds it, and stores it for later retrieval. The README documents the major capabilities; details of some web and status handling are based on partial excerpts.

Main entry points: [`src/ingest.py`](https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/src/ingest.py) (Ingestion Pipeline), [`main.py`](https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/main.py) (CLI and API), [`src/rag.py`](https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/src/rag.py) (RAG Query), [`Data`](https://github.com/shuiii129/agora-rag-ml-assessment/tree/main/Data) (AGORA Dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["CLI and API<br/>[main.py]"]
  node_web_assets["Web Chat UI<br/>[static_assets.py]"]
end

subgraph group_ingestion["Document Ingestion"]
  node_data["AGORA Dataset"]
  node_metadata["Metadata Loader<br/>[ingest.py]"]
  node_text_prep["Clean and Chunk<br/>[ingest.py]"]
  node_ingest["Ingestion Pipeline<br/>[ingest.py]"]
end

subgraph group_retrieval["Retrieval and Storage"]
  node_rag["RAG Query<br/>[rag.py]"]
  node_vector_store[("ChromaDB Index")]
end

subgraph group_integrations["External Integrations"]
  node_gemini{{"Gemini API"}}
end

node_user(("User"))

node_user -->|"submits query"| node_main
node_main -->|"serves UI"| node_web_assets
node_main -->|"runs ingestion"| node_ingest
node_main -->|"runs query"| node_rag
node_data -->|"provides documents"| node_ingest
node_data -->|"provides CSV"| node_metadata
node_ingest -->|"loads metadata"| node_metadata
node_ingest -->|"cleans and chunks"| node_text_prep
node_ingest -->|"requests embeddings"| node_gemini
node_ingest -->|"stores chunks"| node_vector_store
node_rag -->|"embeds and generates"| node_gemini
node_rag -->|"retrieves chunks"| node_vector_store
node_main -->|"returns answer and references"| node_user

click node_main "https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/main.py"
click node_web_assets "https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/api/static_assets.py"
click node_data "https://github.com/shuiii129/agora-rag-ml-assessment/tree/main/Data"
click node_metadata "https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/src/ingest.py"
click node_text_prep "https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/src/ingest.py"
click node_ingest "https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/src/ingest.py"
click node_rag "https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/src/rag.py"
click node_vector_store "https://github.com/shuiii129/agora-rag-ml-assessment/tree/main/chroma_db"

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_main,node_web_assets,node_user toneBlue
class node_data,node_metadata,node_text_prep,node_ingest toneAmber
class node_rag,node_vector_store toneMint
class node_gemini toneRose
```

## Components

### Application

- [CLI and API](https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/main.py): `main.py`
- [Web Chat UI](https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/api/static_assets.py): `api/static_assets.py`

### Document Ingestion

- [AGORA Dataset](https://github.com/shuiii129/agora-rag-ml-assessment/tree/main/Data): `Data`
- [Metadata Loader](https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/src/ingest.py): `src/ingest.py`
- [Clean and Chunk](https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/src/ingest.py): `src/ingest.py`
- [Ingestion Pipeline](https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/src/ingest.py): `src/ingest.py`

### Retrieval and Storage

- [RAG Query](https://github.com/shuiii129/agora-rag-ml-assessment/blob/main/src/rag.py): `src/rag.py`
- [ChromaDB Index](https://github.com/shuiii129/agora-rag-ml-assessment/tree/main/chroma_db): `chroma_db`

### External Integrations

- **Gemini API**

### Other components

- **User**

## Connections

- User → CLI and API: submits query
- CLI and API → Web Chat UI: serves UI
- CLI and API → Ingestion Pipeline: runs ingestion
- CLI and API → RAG Query: runs query
- AGORA Dataset → Ingestion Pipeline: provides documents
- AGORA Dataset → Metadata Loader: provides CSV
- Ingestion Pipeline → Metadata Loader: loads metadata
- Ingestion Pipeline → Clean and Chunk: cleans and chunks
- Ingestion Pipeline → Gemini API: requests embeddings
- Ingestion Pipeline → ChromaDB Index: stores chunks
- RAG Query → Gemini API: embeds and generates
- RAG Query → ChromaDB Index: retrieves chunks
- CLI and API → User: returns answer and references
