# puj-nlp/cev-rag architecture

> Architecture diagram of the GitHub repository puj-nlp/cev-rag, 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/puj-nlp/cev-rag
- Repository: https://github.com/puj-nlp/cev-rag

## Overview

This repository implements a cultural-context-aware RAG system for asking questions over the Colombian Truth Commission archive. A user asks through the web chat; the frontend calls backend routes, where question answering retrieves documents, builds context, and generates an answer with references. Separate chat-session operations persist conversation history, and admin routes provide storage statistics, search, and data import/export. The graph reflects shown calls and wiring; unsampled capabilities are represented only where documented, without inferred internal links.

Main entry points: [`rag-api/src/application/use_cases.py`](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/application/use_cases.py) (Question answering), [`rag-api/src/infrastructure/dependencies.py`](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/infrastructure/dependencies.py) (Dependency wiring), [`rag-api/src/adapters/controllers/frontend_controller.py`](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/controllers/frontend_controller.py) (Frontend routes), [`rag-api/src/main.py`](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/main.py) (FastAPI setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_app["Web app routes<br/>[App.js]"]
  node_chatui["Chat interface"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and application"]
  node_backend["FastAPI setup<br/>[main.py]"]
  node_frontend_routes["Frontend routes"]
  node_api_routes["Chat and question routes<br/>[controllers.py]"]
  node_chat_usecase["Chat sessions<br/>[use_cases.py]"]
  node_domain["RAG domain<br/>[entities.py]"]
  node_ports["Service contracts<br/>[ports.py]"]
  node_dependencies["Dependency wiring<br/>[dependencies.py]"]
  node_auth["API authentication<br/>[auth.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_rag["Retrieval and generation"]
  node_qa_usecase["Question answering<br/>[use_cases.py]"]
  node_context_builder["Context builder<br/>[services.py]"]
  node_milvus["Document retrieval"]
  node_openai_embed["Embedding service<br/>[openai_services.py]"]
  node_openai_llm["Answer generation<br/>[openai_services.py]"]
  node_openai_tools["LLM tools<br/>[openai_tools.py]"]
end

subgraph group_storage["Chat and archive storage"]
  node_sqlite[("SQLite chat store")]
  node_memory[("Memory chat store")]
  node_migration["Chat data migration<br/>[migration.py]"]
  node_db_setup["Database initialization<br/>[database_setup.py]"]
end

subgraph group_ops["Administration"]
  node_admin_routes["Admin routes"]
end

node_visitor(("Researcher"))
node_openai_service["OpenAI service"]
node_milvus_service[("Milvus vector store")]

node_visitor -->|"uses"| node_app
node_app -->|"routes to"| node_chatui
node_chatui -->|"calls"| node_api_client
node_api_client -->|"requests"| node_frontend_routes
node_backend -->|"registers"| node_frontend_routes
node_backend -->|"registers"| node_api_routes
node_backend -->|"registers"| node_admin_routes
node_frontend_routes -->|"invokes"| node_chat_usecase
node_frontend_routes -->|"invokes"| node_qa_usecase
node_api_routes -->|"invokes"| node_chat_usecase
node_api_routes -->|"invokes"| node_qa_usecase
node_qa_usecase -->|"uses"| node_domain
node_chat_usecase -->|"uses"| node_domain
node_qa_usecase -->|"services wired by"| node_dependencies
node_dependencies -->|"constructs"| node_milvus
node_dependencies -->|"constructs"| node_openai_embed
node_dependencies -->|"constructs"| node_openai_llm
node_dependencies -->|"constructs"| node_context_builder
node_dependencies -->|"constructs"| node_sqlite
node_dependencies -->|"constructs"| node_memory
node_qa_usecase -->|"searches documents"| node_milvus
node_qa_usecase -->|"embeds questions"| node_openai_embed
node_qa_usecase -->|"builds context"| node_context_builder
node_qa_usecase -->|"generates answers"| node_openai_llm
node_openai_embed -.->|"calls"| node_openai_service
node_openai_llm -.->|"calls"| node_openai_service
node_chat_usecase -.->|"persists chats"| node_sqlite
node_chat_usecase -.->|"stores chats"| node_memory
node_admin_routes -->|"queries and exports"| node_sqlite
node_admin_routes -->|"imports data"| node_migration
node_backend -->|"initializes"| node_db_setup
node_db_setup -->|"imports legacy data"| node_migration
node_db_setup -->|"checks storage"| node_sqlite
node_config -.->|"configures"| node_milvus_service
node_openai_llm -.->|"tool support"| node_openai_tools
node_frontend_routes -.->|"validates requests"| node_auth
node_api_routes -->|"requires key"| node_auth
node_domain -->|"defines contracts"| node_ports

click node_app "https://github.com/puj-nlp/cev-rag/blob/main/rag-ui/src/App.js"
click node_chatui "https://github.com/puj-nlp/cev-rag/blob/main/rag-ui/src/pages/UnifiedChatInterface.js"
click node_api_client "https://github.com/puj-nlp/cev-rag/blob/main/rag-ui/src/services/api.js"
click node_backend "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/main.py"
click node_frontend_routes "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/controllers/frontend_controller.py"
click node_api_routes "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/controllers/controllers.py"
click node_admin_routes "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/controllers/admin_controller.py"
click node_chat_usecase "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/application/use_cases.py"
click node_qa_usecase "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/application/use_cases.py"
click node_domain "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/domain/entities.py"
click node_ports "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/domain/ports.py"
click node_context_builder "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/infrastructure/services.py"
click node_milvus "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/repositories/milvus_vector_db.py"
click node_openai_embed "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/external/openai_services.py"
click node_openai_llm "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/external/openai_services.py"
click node_openai_tools "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/external/openai_tools.py"
click node_dependencies "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/infrastructure/dependencies.py"
click node_auth "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/infrastructure/auth.py"
click node_config "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/infrastructure/config.py"
click node_sqlite "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/repositories/sqlite_chat_repository.py"
click node_memory "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/repositories/memory_chat_repository.py"
click node_migration "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/repositories/migration.py"
click node_db_setup "https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/infrastructure/database_setup.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_app,node_chatui,node_api_client toneBlue
class node_backend,node_frontend_routes,node_api_routes,node_chat_usecase,node_domain,node_ports,node_dependencies,node_auth,node_config,node_milvus_service toneAmber
class node_qa_usecase,node_context_builder,node_milvus,node_openai_embed,node_openai_llm,node_openai_tools toneMint
class node_sqlite,node_memory,node_migration,node_db_setup toneRose
class node_admin_routes,node_visitor,node_openai_service toneIndigo
```

## Components

### Web interface

- [Web app routes](https://github.com/puj-nlp/cev-rag/blob/main/rag-ui/src/App.js): `rag-ui/src/App.js`
- [Chat interface](https://github.com/puj-nlp/cev-rag/blob/main/rag-ui/src/pages/UnifiedChatInterface.js): `rag-ui/src/pages/UnifiedChatInterface.js`
- [API client](https://github.com/puj-nlp/cev-rag/blob/main/rag-ui/src/services/api.js): `rag-ui/src/services/api.js`

### API and application

- [FastAPI setup](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/main.py): `rag-api/src/main.py`
- [Frontend routes](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/controllers/frontend_controller.py): `rag-api/src/adapters/controllers/frontend_controller.py`
- [Chat and question routes](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/controllers/controllers.py): `rag-api/src/adapters/controllers/controllers.py`
- [Chat sessions](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/application/use_cases.py): `rag-api/src/application/use_cases.py`
- [RAG domain](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/domain/entities.py): `rag-api/src/domain/entities.py`
- [Service contracts](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/domain/ports.py): `rag-api/src/domain/ports.py`
- [Dependency wiring](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/infrastructure/dependencies.py): `rag-api/src/infrastructure/dependencies.py`
- [API authentication](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/infrastructure/auth.py): `rag-api/src/infrastructure/auth.py`
- [Runtime configuration](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/infrastructure/config.py): `rag-api/src/infrastructure/config.py`

### Retrieval and generation

- [Question answering](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/application/use_cases.py): `rag-api/src/application/use_cases.py`
- [Context builder](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/infrastructure/services.py): `rag-api/src/infrastructure/services.py`
- [Document retrieval](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/repositories/milvus_vector_db.py): `rag-api/src/adapters/repositories/milvus_vector_db.py`
- [Embedding service](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/external/openai_services.py): `rag-api/src/adapters/external/openai_services.py`
- [Answer generation](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/external/openai_services.py): `rag-api/src/adapters/external/openai_services.py`
- [LLM tools](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/external/openai_tools.py): `rag-api/src/adapters/external/openai_tools.py`

### Chat and archive storage

- [SQLite chat store](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/repositories/sqlite_chat_repository.py): `rag-api/src/adapters/repositories/sqlite_chat_repository.py`
- [Memory chat store](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/repositories/memory_chat_repository.py): `rag-api/src/adapters/repositories/memory_chat_repository.py`
- [Chat data migration](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/repositories/migration.py): `rag-api/src/adapters/repositories/migration.py`
- [Database initialization](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/infrastructure/database_setup.py): `rag-api/src/infrastructure/database_setup.py`

### Administration

- [Admin routes](https://github.com/puj-nlp/cev-rag/blob/main/rag-api/src/adapters/controllers/admin_controller.py): `rag-api/src/adapters/controllers/admin_controller.py`

### Other components

- **Researcher**
- **OpenAI service**
- **Milvus vector store**

## Connections

- Researcher → Web app routes: uses
- Web app routes → Chat interface: routes to (evidence: `rag-ui/src/App.js`)
- Chat interface → API client: calls (evidence: `rag-ui/src/pages/UnifiedChatInterface.js`)
- API client → Frontend routes: requests (evidence: `rag-ui/src/services/api.js`)
- FastAPI setup → Frontend routes: registers (evidence: `rag-api/src/main.py`)
- FastAPI setup → Chat and question routes: registers (evidence: `rag-api/src/main.py`)
- FastAPI setup → Admin routes: registers (evidence: `rag-api/src/main.py`)
- Frontend routes → Chat sessions: invokes (evidence: `rag-api/src/adapters/controllers/frontend_controller.py`)
- Frontend routes → Question answering: invokes (evidence: `rag-api/src/adapters/controllers/frontend_controller.py`)
- Chat and question routes → Chat sessions: invokes (evidence: `rag-api/src/adapters/controllers/controllers.py`)
- Chat and question routes → Question answering: invokes (evidence: `rag-api/src/adapters/controllers/controllers.py`)
- Question answering → RAG domain: uses (evidence: `rag-api/src/application/use_cases.py`)
- Chat sessions → RAG domain: uses (evidence: `rag-api/src/application/use_cases.py`)
- Question answering → Dependency wiring: services wired by (evidence: `rag-api/src/infrastructure/dependencies.py`)
- Dependency wiring → Document retrieval: constructs (evidence: `rag-api/src/infrastructure/dependencies.py`)
- Dependency wiring → Embedding service: constructs (evidence: `rag-api/src/infrastructure/dependencies.py`)
- Dependency wiring → Answer generation: constructs (evidence: `rag-api/src/infrastructure/dependencies.py`)
- Dependency wiring → Context builder: constructs (evidence: `rag-api/src/infrastructure/dependencies.py`)
- Dependency wiring → SQLite chat store: constructs (evidence: `rag-api/src/infrastructure/dependencies.py`)
- Dependency wiring → Memory chat store: constructs (evidence: `rag-api/src/infrastructure/dependencies.py`)
- Question answering → Document retrieval: searches documents (evidence: `rag-api/src/infrastructure/dependencies.py`)
- Question answering → Embedding service: embeds questions (evidence: `rag-api/src/infrastructure/dependencies.py`)
- Question answering → Context builder: builds context (evidence: `rag-api/src/infrastructure/dependencies.py`)
- Question answering → Answer generation: generates answers (evidence: `rag-api/src/infrastructure/dependencies.py`)
- Embedding service → OpenAI service: calls
- Answer generation → OpenAI service: calls
- Chat sessions → SQLite chat store: persists chats
- Chat sessions → Memory chat store: stores chats
- Admin routes → SQLite chat store: queries and exports (evidence: `rag-api/src/adapters/controllers/admin_controller.py`)
- Admin routes → Chat data migration: imports data (evidence: `rag-api/src/adapters/controllers/admin_controller.py`)
- FastAPI setup → Database initialization: initializes (evidence: `rag-api/src/main.py`)
- Database initialization → Chat data migration: imports legacy data (evidence: `rag-api/src/infrastructure/database_setup.py`)
- Database initialization → SQLite chat store: checks storage (evidence: `rag-api/src/infrastructure/database_setup.py`)
- Runtime configuration → Milvus vector store: configures
- Answer generation → LLM tools: tool support (evidence: `rag-api/src/adapters/external/openai_services.py`)
- Frontend routes → API authentication: validates requests (evidence: `rag-api/src/adapters/controllers/frontend_controller.py`)
- Chat and question routes → API authentication: requires key (evidence: `rag-api/src/adapters/controllers/controllers.py`)
- RAG domain → Service contracts: defines contracts (evidence: `rag-api/src/domain/ports.py`)