# sts87/mini-rag architecture

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

- Interactive diagram: https://gitdiagram.com/sts87/mini-rag
- Repository: https://github.com/sts87/mini-rag

## Overview

Enterprise Knowledge AI is a Streamlit RAG assistant: employees ask questions, the app retrieves relevant chunks from a persistent FAISS index, generates a grounded answer with citations, and logs the interaction. A separate indexing command loads and tags PDFs, splits them into chunks, embeds them, and saves the index. The README also describes OCI deployment, but deployment wiring is omitted because the available source excerpts do not show its runtime relationships.

Main entry points: [`src/streamlit_app.py`](https://github.com/sts87/mini-rag/blob/main/src/streamlit_app.py) (Streamlit interface), [`src/app/indexer.py`](https://github.com/sts87/mini-rag/blob/main/src/app/indexer.py) (Embedding indexer), [`src/scripts/build_index.py`](https://github.com/sts87/mini-rag/blob/main/src/scripts/build_index.py) (Index builder), [`src/app/retriever.py`](https://github.com/sts87/mini-rag/blob/main/src/app/retriever.py) (Semantic retriever)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Document indexing"]
  node_pdfs["Corporate PDFs"]
  node_build_command["Index builder<br/>[build_index.py]"]
  node_loader["PDF loader<br/>[loader.py]"]
  node_chunker["Document chunker<br/>[chunker.py]"]
  node_indexer["Embedding indexer<br/>[indexer.py]"]
  node_vector_store[("FAISS vector store<br/>[indexer.py]")]
end

subgraph group_query["Question answering"]
  node_retriever["Semantic retriever<br/>[retriever.py]"]
  node_faiss_search["FAISS search<br/>[retriever.py]"]
  node_generator["Answer generator<br/>[generator.py]"]
end

subgraph group_interface["User interaction"]
  node_streamlit["Streamlit interface<br/>[streamlit_app.py]"]
  node_answer["Answer and citations<br/>[generator.py]"]
end

subgraph group_records["Interaction logging"]
  node_logger["Interaction logger<br/>[logger.py]"]
  node_jsonl[("JSONL interaction log")]
end

node_employee(("Employee"))
node_cohere{{"Cohere API"}}

node_employee -->|"asks question"| node_streamlit
node_pdfs -->|"loads pages"| node_loader
node_build_command -->|"calls"| node_loader
node_build_command -->|"calls"| node_chunker
node_build_command -->|"calls"| node_indexer
node_loader -->|"passes documents"| node_chunker
node_chunker -->|"passes chunks"| node_indexer
node_indexer -->|"requests embeddings"| node_cohere
node_indexer -->|"writes index and chunks"| node_vector_store
node_streamlit -->|"loads index"| node_indexer
node_streamlit -->|"requests retrieval"| node_retriever
node_retriever -->|"embeds query"| node_cohere
node_retriever -->|"searches vectors"| node_faiss_search
node_faiss_search -->|"searches loaded index"| node_vector_store
node_streamlit -->|"requests answer"| node_generator
node_generator -->|"requests chat completion"| node_cohere
node_generator -->|"formats answer and sources"| node_answer
node_answer -->|"displays"| node_streamlit
node_streamlit -->|"records interaction"| node_logger
node_logger -->|"appends record"| node_jsonl

click node_pdfs "https://github.com/sts87/mini-rag/tree/main/data/documents"
click node_build_command "https://github.com/sts87/mini-rag/blob/main/src/scripts/build_index.py"
click node_loader "https://github.com/sts87/mini-rag/blob/main/src/app/loader.py"
click node_chunker "https://github.com/sts87/mini-rag/blob/main/src/app/chunker.py"
click node_indexer "https://github.com/sts87/mini-rag/blob/main/src/app/indexer.py"
click node_vector_store "https://github.com/sts87/mini-rag/blob/main/src/app/indexer.py"
click node_streamlit "https://github.com/sts87/mini-rag/blob/main/src/streamlit_app.py"
click node_retriever "https://github.com/sts87/mini-rag/blob/main/src/app/retriever.py"
click node_faiss_search "https://github.com/sts87/mini-rag/blob/main/src/app/retriever.py"
click node_generator "https://github.com/sts87/mini-rag/blob/main/src/app/generator.py"
click node_answer "https://github.com/sts87/mini-rag/blob/main/src/app/generator.py"
click node_logger "https://github.com/sts87/mini-rag/blob/main/src/app/logger.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_pdfs,node_build_command,node_loader,node_chunker,node_indexer,node_vector_store toneBlue
class node_retriever,node_faiss_search,node_generator toneAmber
class node_streamlit,node_answer,node_cohere toneMint
class node_logger,node_jsonl toneRose
class node_employee toneIndigo
```

## Components

### Document indexing

- [Corporate PDFs](https://github.com/sts87/mini-rag/tree/main/data/documents): `data/documents`
- [Index builder](https://github.com/sts87/mini-rag/blob/main/src/scripts/build_index.py): `src/scripts/build_index.py`
- [PDF loader](https://github.com/sts87/mini-rag/blob/main/src/app/loader.py): `src/app/loader.py`
- [Document chunker](https://github.com/sts87/mini-rag/blob/main/src/app/chunker.py): `src/app/chunker.py`
- [Embedding indexer](https://github.com/sts87/mini-rag/blob/main/src/app/indexer.py): `src/app/indexer.py`
- [FAISS vector store](https://github.com/sts87/mini-rag/blob/main/src/app/indexer.py): `src/app/indexer.py`

### Question answering

- [Semantic retriever](https://github.com/sts87/mini-rag/blob/main/src/app/retriever.py): `src/app/retriever.py`
- [FAISS search](https://github.com/sts87/mini-rag/blob/main/src/app/retriever.py): `src/app/retriever.py`
- [Answer generator](https://github.com/sts87/mini-rag/blob/main/src/app/generator.py): `src/app/generator.py`

### User interaction

- [Streamlit interface](https://github.com/sts87/mini-rag/blob/main/src/streamlit_app.py): `src/streamlit_app.py`
- [Answer and citations](https://github.com/sts87/mini-rag/blob/main/src/app/generator.py): `src/app/generator.py`

### Interaction logging

- [Interaction logger](https://github.com/sts87/mini-rag/blob/main/src/app/logger.py): `src/app/logger.py`
- **JSONL interaction log**

### Other components

- **Employee**
- **Cohere API**

## Connections

- Employee → Streamlit interface: asks question
- Corporate PDFs → PDF loader: loads pages
- Index builder → PDF loader: calls
- Index builder → Document chunker: calls
- Index builder → Embedding indexer: calls
- PDF loader → Document chunker: passes documents
- Document chunker → Embedding indexer: passes chunks
- Embedding indexer → Cohere API: requests embeddings
- Embedding indexer → FAISS vector store: writes index and chunks
- Streamlit interface → Embedding indexer: loads index
- Streamlit interface → Semantic retriever: requests retrieval
- Semantic retriever → Cohere API: embeds query
- Semantic retriever → FAISS search: searches vectors
- FAISS search → FAISS vector store: searches loaded index
- Streamlit interface → Answer generator: requests answer
- Answer generator → Cohere API: requests chat completion
- Answer generator → Answer and citations: formats answer and sources
- Answer and citations → Streamlit interface: displays
- Streamlit interface → Interaction logger: records interaction
- Interaction logger → JSONL interaction log: appends record