# namansharma2408/causal-rag architecture

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

- Interactive diagram: https://gitdiagram.com/namansharma2408/causal-rag
- Repository: https://github.com/namansharma2408/causal-rag

## Overview

1. **What this repository is**
   - A Python-based conversational analytics system for transcript data.
   - The core architecture is a **multi-agent RAG pipeline**: retrieve relevant transcript evidence, reason over it, optionally cross-check it, and return a grounded answer.

2. **Primary runtime and entry points**
   - The app is built around a **FastAPI server** (`server.py`) with supporting orchestration in `app.py` and `api.py`.
   - `__main__.py` and `cli.py` suggest the system can also be started from the command line, not only through Docker.
   - `frontend.html` is a lightweight browser UI that talks to the backend API.

3. **End-user request flow**
   - A user submits a question in the web UI or via `POST /api/query`.
   - The request is handled by the server layer, passed into the application/session orchestration layer, and then into the core RAG pipeline in `ragSystem.py`.
   - The response is returned as a conversational answer, with optional proof and quality checks.

4. **Core orchestration boundary**
   - `ragSystem.py` is the main pipeline coordinator.
   - It wires together the agents in the correct order and manages the overall retrieval-to-answer flow.
   - This file is the best place to think of as the “brain” of the system when drawing the architecture.

5. **Agent pipeline**
   - The repository defines a staged agent chain in `agents/`:
     - `Decomposer` breaks the user question into subproblems.
     - `Router` decides how to handle the query and likely what retrieval path to use.
     - `Retriever` pulls candidate evidence.
     - `Reranker` improves candidate ordering.
     - `Extractor` selects the most relevant supporting snippets.
     - `Reasoner` synthesizes the final answer.
     - `Proof` adds evidence/justification.
     - `QualityChecker` evaluates answer quality.
   - `thinking.py` and `proof.py` indicate optional deeper reasoning and verification paths.

6. **Retrieval architecture**
   - The README describes **hybrid retrieval**: vector similarity plus BM25-style keyword scoring.
   - That means the retrieval layer is not purely embedding-based; it combines semantic and lexical search for better transcript lookup.
   - The retriever/reranker/extractor stages form the evidence selection boundary before generation.

7. **Model and provider layer**
   - `services/llmProvider.py`, `services/embedding.py`, and `services/ollama.py` abstract external model access.
   - Gemini is the required default LLM provider via `GEMINI_API_KEY`.
   - Ollama is an optional local inference path used for “Thinking Mode,” which enables multi-model consensus.
   - This is a key deployment boundary: cloud LLM calls versus local model serving.

8. **State, memory, and persistence**
   - `services/memory.py` and `models.py` indicate shared conversation/session structures.
   - The README says session state is persisted in `chatSessions/*.json`, so chat continuity is at least partly file-backed.
   - `services/mongodb.py` and `scripts/initMongoDb.py` show MongoDB is also part of the system, likely for transcript storage or indexed data management.
   - This creates a split between short-lived chat/session memory and longer-lived data persistence.

9. **Transcript data boundary**
   - `services/transcripts.py` is the domain-specific data access layer for transcript content.
   - In architectural terms, transcript data flows from storage into retrieval, then through the agent pipeline, and back out as grounded answers.
   - This is the main business-data boundary of the repo.

10. **Deployment topology**
   - `docker-compose.yml`, `Dockerfile`, and `scripts/dockerEntrypoint.sh` define a containerized runtime.
   - The README implies at least two containers/services in practice: the app and MongoDB.
   - The app expects environment configuration from `.env`, especially `GEMINI_API_KEY`, and optionally MongoDB/Ollama endpoints.

11. **Operational tooling**
   - `Makefile` provides lifecycle commands such as build, up, down, logs, and cleanup.
   - This is important for the architecture diagram because the system is designed to be run as a packaged local stack, not just as a library.

12. **Suggested architecture diagram boundaries**
   - **Client boundary:** browser UI / API consumer.
   - **Application boundary:** FastAPI server + request/session orchestration.
   - **Reasoning boundary:** `ragSystem.py` plus the agent chain.
   - **Data boundary:** transcripts, chat session JSON, MongoDB.
   - **External service boundary:** Gemini API and optional Ollama local models.

Main entry points: [`agents/retriever.py`](https://github.com/namansharma2408/causal-rag/blob/main/agents/retriever.py) (Retriever), [`app.py`](https://github.com/namansharma2408/causal-rag/blob/main/app.py) (App Orchestration), [`server.py`](https://github.com/namansharma2408/causal-rag/blob/main/server.py) (Server), [`ragSystem.py`](https://github.com/namansharma2408/causal-rag/blob/main/ragSystem.py) (RAG System)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser_ui["Browser UI<br/>web client<br/>[frontend.html]"]
  node_cli_entry["CLI Entry<br/>command entry<br/>[cli.py]"]
  node_main_entry(("Module Main<br/>runtime entry<br/>[__main__.py]"))
end

subgraph group_app["Application"]
  node_server["Server<br/>FastAPI app<br/>[server.py]"]
  node_api_layer["API Layer<br/>request routing<br/>[api.py]"]
  node_app_orch["App Orchestration<br/>session flow<br/>[app.py]"]
end

subgraph group_reasoning["Reasoning"]
  node_rag_system{{"RAG System<br/>pipeline coordinator<br/>[ragSystem.py]"}}
  node_router["Router<br/>query routing<br/>[router.py]"]
  node_decomposer["Decomposer<br/>subquestion split<br/>[decomposer.py]"]
  node_retriever["Retriever<br/>evidence fetch<br/>[retriever.py]"]
  node_reranker["Reranker<br/>ranking<br/>[reranker.py]"]
  node_extractor["Extractor<br/>snippet selection<br/>[extractor.py]"]
  node_reasoner["Reasoner<br/>answer synthesis<br/>[reasoner.py]"]
  node_proof["Proof<br/>justification<br/>[proof.py]"]
  node_quality["Quality Check<br/>evaluation<br/>[quality.py]"]
  node_thinking{{"Thinking Mode<br/>consensus path<br/>[thinking.py]"}}
end

subgraph group_data["Data"]
  node_transcripts["Transcripts<br/>domain data access<br/>[transcripts.py]"]
  node_memory[("Memory<br/>session store<br/>[memory.py]")]
  node_models["Models<br/>shared schemas<br/>[models.py]"]
  node_mongo[("MongoDB<br/>persistent store<br/>[mongodb.py]")]
end

subgraph group_external["External"]
  node_llm["LLM Provider<br/>cloud model access<br/>[llmProvider.py]"]
  node_embed["Embeddings<br/>vector model access<br/>[embedding.py]"]
  node_ollama["Ollama<br/>local model runtime<br/>[ollama.py]"]
end

subgraph group_deploy["Deployment"]
  node_compose["Compose Stack<br/>container runtime<br/>[docker-compose.yml]"]
  node_dockerfile["App Image<br/>container build"]
  node_entrypoint["Entrypoint<br/>container startup"]
  node_makefile["Makefile<br/>ops tooling"]
end

node_browser_ui -->|"chat request"| node_server
node_cli_entry -->|"start"| node_app_orch
node_main_entry -->|"boot"| node_server
node_server -->|"route"| node_api_layer
node_api_layer -->|"session flow"| node_app_orch
node_app_orch -->|"query"| node_rag_system
node_rag_system -->|"dispatch"| node_router
node_router -->|"split"| node_decomposer
node_decomposer -->|"retrieve"| node_retriever
node_retriever -->|"fetch"| node_transcripts
node_retriever -->|"vectorize"| node_embed
node_retriever -->|"lookup"| node_mongo
node_retriever -->|"candidates"| node_reranker
node_reranker -->|"top evidence"| node_extractor
node_extractor -->|"context"| node_reasoner
node_reasoner -->|"generate"| node_llm
node_reasoner -.->|"justify"| node_proof
node_proof -.->|"check"| node_quality
node_rag_system -.->|"optional path"| node_thinking
node_thinking -.->|"local inference"| node_ollama
node_app_orch -->|"store session"| node_memory
node_memory -->|"serialize"| node_models
node_app_orch -->|"use schemas"| node_models
node_server -.->|"deploys with"| node_compose
node_compose -.->|"service"| node_mongo
node_dockerfile -.->|"starts"| node_entrypoint
node_makefile -.->|"orchestrates"| node_compose

click node_browser_ui "https://github.com/namansharma2408/causal-rag/blob/main/frontend.html"
click node_cli_entry "https://github.com/namansharma2408/causal-rag/blob/main/cli.py"
click node_main_entry "https://github.com/namansharma2408/causal-rag/blob/main/__main__.py"
click node_server "https://github.com/namansharma2408/causal-rag/blob/main/server.py"
click node_api_layer "https://github.com/namansharma2408/causal-rag/blob/main/api.py"
click node_app_orch "https://github.com/namansharma2408/causal-rag/blob/main/app.py"
click node_rag_system "https://github.com/namansharma2408/causal-rag/blob/main/ragSystem.py"
click node_router "https://github.com/namansharma2408/causal-rag/blob/main/agents/router.py"
click node_decomposer "https://github.com/namansharma2408/causal-rag/blob/main/agents/decomposer.py"
click node_retriever "https://github.com/namansharma2408/causal-rag/blob/main/agents/retriever.py"
click node_reranker "https://github.com/namansharma2408/causal-rag/blob/main/agents/reranker.py"
click node_extractor "https://github.com/namansharma2408/causal-rag/blob/main/agents/extractor.py"
click node_reasoner "https://github.com/namansharma2408/causal-rag/blob/main/agents/reasoner.py"
click node_proof "https://github.com/namansharma2408/causal-rag/blob/main/agents/proof.py"
click node_quality "https://github.com/namansharma2408/causal-rag/blob/main/agents/quality.py"
click node_thinking "https://github.com/namansharma2408/causal-rag/blob/main/agents/thinking.py"
click node_transcripts "https://github.com/namansharma2408/causal-rag/blob/main/services/transcripts.py"
click node_memory "https://github.com/namansharma2408/causal-rag/blob/main/services/memory.py"
click node_models "https://github.com/namansharma2408/causal-rag/blob/main/models.py"
click node_mongo "https://github.com/namansharma2408/causal-rag/blob/main/services/mongodb.py"
click node_llm "https://github.com/namansharma2408/causal-rag/blob/main/services/llmProvider.py"
click node_embed "https://github.com/namansharma2408/causal-rag/blob/main/services/embedding.py"
click node_ollama "https://github.com/namansharma2408/causal-rag/blob/main/services/ollama.py"
click node_compose "https://github.com/namansharma2408/causal-rag/blob/main/docker-compose.yml"
click node_dockerfile "https://github.com/namansharma2408/causal-rag/tree/main/Dockerfile"
click node_entrypoint "https://github.com/namansharma2408/causal-rag/blob/main/scripts/dockerEntrypoint.sh"
click node_makefile "https://github.com/namansharma2408/causal-rag/tree/main/Makefile"

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_browser_ui,node_cli_entry,node_main_entry toneBlue
class node_server,node_api_layer,node_app_orch toneAmber
class node_rag_system,node_router,node_decomposer,node_retriever,node_reranker,node_extractor,node_reasoner,node_proof,node_quality,node_thinking toneMint
class node_transcripts,node_memory,node_models,node_mongo toneRose
class node_llm,node_embed,node_ollama toneIndigo
class node_compose,node_dockerfile,node_entrypoint,node_makefile toneTeal
```

## Components

### Client

User-facing request sources

- [Browser UI](https://github.com/namansharma2408/causal-rag/blob/main/frontend.html): web client · Lightweight in-browser chat surface · `frontend.html`
- [CLI Entry](https://github.com/namansharma2408/causal-rag/blob/main/cli.py): command entry · Command-line startup path · `cli.py`
- [Module Main](https://github.com/namansharma2408/causal-rag/blob/main/__main__.py): runtime entry · Package entrypoint for local execution · `__main__.py`

### Application

HTTP API and orchestration entrypoints

- [Server](https://github.com/namansharma2408/causal-rag/blob/main/server.py): FastAPI app · HTTP server and API surface · `server.py`
- [API Layer](https://github.com/namansharma2408/causal-rag/blob/main/api.py): request routing · API handlers and request translation · `api.py`
- [App Orchestration](https://github.com/namansharma2408/causal-rag/blob/main/app.py): session flow · Application/session coordination · `app.py`

### Reasoning

RAG pipeline and agent chain

- [RAG System](https://github.com/namansharma2408/causal-rag/blob/main/ragSystem.py): pipeline coordinator · Main retrieval-to-answer workflow · `ragSystem.py`
- [Router](https://github.com/namansharma2408/causal-rag/blob/main/agents/router.py): query routing · Chooses handling path for a query · `agents/router.py`
- [Decomposer](https://github.com/namansharma2408/causal-rag/blob/main/agents/decomposer.py): subquestion split · Breaks a question into smaller tasks · `agents/decomposer.py`
- [Retriever](https://github.com/namansharma2408/causal-rag/blob/main/agents/retriever.py): evidence fetch · Pulls candidate transcript evidence · `agents/retriever.py`
- [Reranker](https://github.com/namansharma2408/causal-rag/blob/main/agents/reranker.py): ranking · Reorders retrieved candidates · `agents/reranker.py`
- [Extractor](https://github.com/namansharma2408/causal-rag/blob/main/agents/extractor.py): snippet selection · Selects the most relevant supporting snippets · `agents/extractor.py`
- [Reasoner](https://github.com/namansharma2408/causal-rag/blob/main/agents/reasoner.py): answer synthesis · Synthesizes the grounded response · `agents/reasoner.py`
- [Proof](https://github.com/namansharma2408/causal-rag/blob/main/agents/proof.py): justification · Adds evidence and justification · `agents/proof.py`
- [Quality Check](https://github.com/namansharma2408/causal-rag/blob/main/agents/quality.py): evaluation · Assesses answer quality · `agents/quality.py`
- [Thinking Mode](https://github.com/namansharma2408/causal-rag/blob/main/agents/thinking.py): consensus path · Optional deeper reasoning and multi-model checks · `agents/thinking.py`

### Data

Conversation, transcript, and persistence boundaries

- [Transcripts](https://github.com/namansharma2408/causal-rag/blob/main/services/transcripts.py): domain data access · Transcript retrieval and domain data access · `services/transcripts.py`
- [Memory](https://github.com/namansharma2408/causal-rag/blob/main/services/memory.py): session store · Conversation/session state management · `services/memory.py`
- [Models](https://github.com/namansharma2408/causal-rag/blob/main/models.py): shared schemas · Shared data structures for sessions and messages · `models.py`
- [MongoDB](https://github.com/namansharma2408/causal-rag/blob/main/services/mongodb.py): persistent store · Long-lived transcript or index storage · `services/mongodb.py`

### External

Model and service integrations

- [LLM Provider](https://github.com/namansharma2408/causal-rag/blob/main/services/llmProvider.py): cloud model access · Abstraction over external LLM calls · `services/llmProvider.py`
- [Embeddings](https://github.com/namansharma2408/causal-rag/blob/main/services/embedding.py): vector model access · Embedding generation for retrieval · `services/embedding.py`
- [Ollama](https://github.com/namansharma2408/causal-rag/blob/main/services/ollama.py): local model runtime · Optional local inference path · `services/ollama.py`

### Deployment

Container and local runtime tooling

- [Compose Stack](https://github.com/namansharma2408/causal-rag/blob/main/docker-compose.yml): container runtime · Containerized app and database topology · `docker-compose.yml`
- [App Image](https://github.com/namansharma2408/causal-rag/tree/main/Dockerfile): container build · Application container build definition · `Dockerfile`
- [Entrypoint](https://github.com/namansharma2408/causal-rag/blob/main/scripts/dockerEntrypoint.sh): container startup · Container startup script · `scripts/dockerEntrypoint.sh`
- [Makefile](https://github.com/namansharma2408/causal-rag/tree/main/Makefile): ops tooling · Lifecycle commands for local stack · `Makefile`

## Connections

- Browser UI → Server: chat request · User submits a question through the web UI
- CLI Entry → App Orchestration: start · CLI launches the application flow
- Module Main → Server: boot · Module entrypoint starts the API server
- Server → API Layer: route · HTTP requests are handed to API handlers
- API Layer → App Orchestration: session flow · Request is translated into app/session orchestration
- App Orchestration → RAG System: query · Application layer invokes the core RAG pipeline
- RAG System → Router: dispatch · Pipeline chooses a handling path
- Router → Decomposer: split · Complex queries are decomposed into subproblems
- Decomposer → Retriever: retrieve · Subproblems drive evidence lookup
- Retriever → Transcripts: fetch · Transcript content is loaded for search
- Retriever → Embeddings: vectorize · Embedding-based similarity is used in retrieval
- Retriever → MongoDB: lookup · Persistent transcript or index data can be queried
- Retriever → Reranker: candidates · Retrieved evidence is forwarded for ranking
- Reranker → Extractor: top evidence · Best candidates are distilled into snippets
- Extractor → Reasoner: context · Selected evidence becomes generation context
- Reasoner → LLM Provider: generate · Final answer synthesis uses the LLM provider
- Reasoner → Proof: justify · Optional evidence-backed explanation is added
- Proof → Quality Check: check · Answer and proof can be evaluated for quality
- RAG System → Thinking Mode: optional path · Thinking mode enables deeper multi-model reasoning
- Thinking Mode → Ollama: local inference · Optional local model execution for consensus or checks
- App Orchestration → Memory: store session · Conversation state is persisted during the session
- Memory → Models: serialize · Session and message structures define stored state
- App Orchestration → Models: use schemas · Application logic uses shared data models
- Server → Compose Stack: deploys with · Server is commonly run as part of the stack
- Compose Stack → MongoDB: service · Container stack includes MongoDB
- App Image → Entrypoint: starts · Container image uses the startup script
- Makefile → Compose Stack: orchestrates · Make targets manage the containerized stack
