# devfullcycle/mba-ia-rag architecture

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

- Interactive diagram: https://gitdiagram.com/devfullcycle/mba-ia-rag
- Repository: https://github.com/devfullcycle/mba-ia-rag

## Overview

RAG Knowledge Chat ingests Markdown knowledge documents, indexes chunks in Postgres/pgvector, and answers user questions through a shared retrieval-augmented pipeline. The documented query flow is planning (including clarification), filtered retrieval, optional reranking, answer generation, and application-built sources; users can enter through terminal chat or the HTTP API. Incremental indexing tracks document hashes and chunk IDs in a manifest. The README documents observability for pipeline runs. Some internal calls are not shown in the excerpts, so those stage links cite the README rather than implying additional source-level wiring.

Main entry points: [`app/rag_pipeline.py`](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/rag_pipeline.py) (RAG pipeline), [`app/index.py`](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/index.py) (Incremental indexer), [`app/retrieve.py`](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/retrieve.py) (Filtered retrieval), [`app/ingest.py`](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/ingest.py) (Document chunking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion and indexing"]
  node_knowledge["Markdown knowledge base"]
  node_ingestor["Document chunking<br/>[ingest.py]"]
  node_chunks["Chunk JSONL<br/>[ingest.py]"]
  node_indexer["Incremental indexer<br/>[index.py]"]
  node_manifest["Index manifest<br/>[manifest.py]"]
end

subgraph group_query["Question answering"]
  node_pipeline["RAG pipeline<br/>[rag_pipeline.py]"]
  node_planner["Query planner<br/>[query_planner.py]"]
  node_retrieval["Filtered retrieval<br/>[retrieve.py]"]
  node_reranker["Chunk reranker<br/>[rerank.py]"]
  node_answer_sources["Answer and sources<br/>[rag_pipeline.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_terminal["Terminal chat<br/>[rag_chat.py]"]
  node_api["HTTP API<br/>[api.py]"]
end

subgraph group_runtime["Runtime infrastructure"]
  node_pgvector[("Postgres pgvector")]
  node_openai["OpenAI models"]
  node_config["Settings<br/>[config.py]"]
  node_db["Database access<br/>[db.py]"]
end

node_user(("User"))

node_user -->|"asks"| node_terminal
node_user -->|"posts question"| node_api
node_terminal -->|"runs"| node_pipeline
node_api -->|"runs"| node_pipeline
node_knowledge -->|"reads"| node_ingestor
node_ingestor -->|"writes"| node_chunks
node_chunks -->|"loads"| node_indexer
node_indexer -->|"reads and writes"| node_manifest
node_indexer -->|"indexes chunks"| node_pgvector
node_indexer -->|"embeds chunks"| node_openai
node_pipeline -->|"plans query"| node_planner
node_pipeline -->|"retrieves chunks"| node_retrieval
node_pipeline -->|"reranks chunks"| node_reranker
node_pipeline -->|"generates answer"| node_answer_sources
node_planner -->|"plans with model"| node_openai
node_retrieval -->|"searches"| node_pgvector
node_retrieval -->|"embeds query"| node_openai
node_reranker -->|"selects chunks"| node_openai
node_answer_sources -->|"generates answer"| node_openai
node_pipeline -->|"connects store"| node_pgvector
node_db -->|"connects"| node_pgvector
node_config -->|"configures"| node_db

click node_knowledge "https://github.com/devfullcycle/mba-ia-rag/tree/main/knowledge_base"
click node_ingestor "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/ingest.py"
click node_chunks "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/ingest.py"
click node_indexer "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/index.py"
click node_manifest "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/manifest.py"
click node_pipeline "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/rag_pipeline.py"
click node_planner "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/query_planner.py"
click node_retrieval "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/retrieve.py"
click node_reranker "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/rerank.py"
click node_answer_sources "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/rag_pipeline.py"
click node_terminal "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/rag_chat.py"
click node_api "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/api.py"
click node_config "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/config.py"
click node_db "https://github.com/devfullcycle/mba-ia-rag/blob/main/app/db.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_knowledge,node_ingestor,node_chunks,node_indexer,node_manifest,node_user toneBlue
class node_pipeline,node_planner,node_retrieval,node_reranker,node_answer_sources toneAmber
class node_terminal,node_api toneMint
class node_pgvector,node_openai,node_config,node_db toneRose
```

## Components

### Ingestion and indexing

- [Markdown knowledge base](https://github.com/devfullcycle/mba-ia-rag/tree/main/knowledge_base): `knowledge_base`
- [Document chunking](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/ingest.py): `app/ingest.py`
- [Chunk JSONL](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/ingest.py): `app/ingest.py`
- [Incremental indexer](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/index.py): `app/index.py`
- [Index manifest](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/manifest.py): `app/manifest.py`

### Question answering

- [RAG pipeline](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/rag_pipeline.py): `app/rag_pipeline.py`
- [Query planner](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/query_planner.py): `app/query_planner.py`
- [Filtered retrieval](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/retrieve.py): `app/retrieve.py`
- [Chunk reranker](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/rerank.py): `app/rerank.py`
- [Answer and sources](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/rag_pipeline.py): `app/rag_pipeline.py`

### User interfaces

- [Terminal chat](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/rag_chat.py): `app/rag_chat.py`
- [HTTP API](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/api.py): `app/api.py`

### Runtime infrastructure

- **Postgres pgvector**
- **OpenAI models**
- [Settings](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/config.py): `app/config.py`
- [Database access](https://github.com/devfullcycle/mba-ia-rag/blob/main/app/db.py): `app/db.py`

### Other components

- **User**

## Connections

- User → Terminal chat: asks (evidence: `README.md`)
- User → HTTP API: posts question (evidence: `README.md`)
- Terminal chat → RAG pipeline: runs (evidence: `app/rag_chat.py`)
- HTTP API → RAG pipeline: runs (evidence: `README.md`)
- Markdown knowledge base → Document chunking: reads (evidence: `app/ingest.py`)
- Document chunking → Chunk JSONL: writes (evidence: `app/ingest.py`)
- Chunk JSONL → Incremental indexer: loads (evidence: `app/index.py`)
- Incremental indexer → Index manifest: reads and writes (evidence: `app/index.py`)
- Incremental indexer → Postgres pgvector: indexes chunks (evidence: `app/index.py`)
- Incremental indexer → OpenAI models: embeds chunks (evidence: `README.md`)
- RAG pipeline → Query planner: plans query (evidence: `README.md`)
- RAG pipeline → Filtered retrieval: retrieves chunks (evidence: `README.md`)
- RAG pipeline → Chunk reranker: reranks chunks (evidence: `README.md`)
- RAG pipeline → Answer and sources: generates answer (evidence: `README.md`)
- Query planner → OpenAI models: plans with model (evidence: `README.md`)
- Filtered retrieval → Postgres pgvector: searches (evidence: `app/retrieve.py`)
- Filtered retrieval → OpenAI models: embeds query (evidence: `app/retrieve.py`)
- Chunk reranker → OpenAI models: selects chunks (evidence: `README.md`)
- Answer and sources → OpenAI models: generates answer (evidence: `README.md`)
- RAG pipeline → Postgres pgvector: connects store (evidence: `app/rag_pipeline.py`)
- Database access → Postgres pgvector: connects (evidence: `app/db.py`)
- Settings → Database access: configures (evidence: `app/db.py`)