# muthukumar-selvarasu/video-rag-with-guardrails-evals architecture

> Architecture diagram of the GitHub repository muthukumar-selvarasu/video-rag-with-guardrails-evals, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muthukumar-selvarasu/video-rag-with-guardrails-evals
- Repository: https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals

## Overview

This is a timestamp-aware video transcript RAG application. Users submit a question through the web interface; the API validates it, retrieves transcript passages, synthesizes a grounded answer, applies output checks, and returns timestamped results for display. A separate agent entry point provides a guarded retrieval workflow. The repository also includes transcript ingestion and indexing for preparing searchable data. The README documents UI and API capabilities not fully visible in the excerpts; edges based on those flows cite the README.

Main entry points: [`api/index.py`](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/api/index.py) (FastAPI endpoints), [`templates/index.html`](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/templates/index.html) (Web interface), [`src/guardrails/router.py`](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/guardrails/router.py) (Guardrail router), [`src/ingestion/pipeline.py`](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/pipeline.py) (Ingestion pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web interface<br/>[index.html]"]
end

subgraph group_query["Query and safeguards"]
  node_api["FastAPI endpoints<br/>[index.py]"]
  node_input_guard["Input checks<br/>[input_guard.py]"]
  node_output_guard["Output checks<br/>[output_guard.py]"]
  node_router["Guardrail router<br/>[router.py]"]
  node_synthesis["Answer synthesis<br/>[index.py]"]
end

subgraph group_knowledge["Transcript knowledge"]
  node_search["Hybrid transcript search<br/>[search.py]"]
  node_index_data["Preindexed embeddings"]
  node_transcriber["Transcript parsing<br/>[transcriber.py]"]
  node_chunker["Timestamp chunking<br/>[chunker.py]"]
  node_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_embedder["Chroma indexing<br/>[embedder.py]"]
  node_chroma[("Chroma store")]
  node_preindexer["Preindex generation<br/>[preindexer.py]"]
end

subgraph group_agent["Agent workflow"]
  node_agent_main["Agent entry point<br/>[main.py]"]
  node_agent_tools["Transcript search tool<br/>[tools.py]"]
end

node_user(("User"))
node_llm{{"LLM provider"}}

node_user -->|"asks questions"| node_web
node_web -->|"sends requests"| node_api
node_api -->|"checks query"| node_input_guard
node_api -->|"retrieves passages"| node_search
node_search -->|"reads vectors"| node_index_data
node_api -->|"builds answer"| node_synthesis
node_synthesis -.->|"requests synthesis"| node_llm
node_api -->|"checks response"| node_output_guard
node_api -->|"returns answer"| node_web
node_web -->|"shows timestamps"| node_user
node_api -.->|"uses guarded flow"| node_router
node_router -->|"validates input"| node_input_guard
node_router -->|"validates output"| node_output_guard
node_pipeline -->|"loads transcripts"| node_transcriber
node_pipeline -->|"chunks transcripts"| node_chunker
node_pipeline -->|"indexes chunks"| node_embedder
node_embedder -->|"writes chunks"| node_chroma
node_preindexer -->|"uses chunking"| node_chunker
node_agent_main -->|"guards execution"| node_router
node_agent_main -->|"registers tool"| node_agent_tools
node_agent_tools -->|"queries transcripts"| node_search
node_agent_main -.->|"configures agent"| node_llm

click node_web "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/templates/index.html"
click node_api "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/api/index.py"
click node_input_guard "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/guardrails/input_guard.py"
click node_output_guard "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/guardrails/output_guard.py"
click node_router "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/guardrails/router.py"
click node_synthesis "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/api/index.py"
click node_search "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/search.py"
click node_index_data "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/data/preindexed_embeddings.json"
click node_transcriber "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/transcriber.py"
click node_chunker "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/chunker.py"
click node_pipeline "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/pipeline.py"
click node_embedder "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/embedder.py"
click node_chroma "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/tree/main/data/chroma_db"
click node_preindexer "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/preindexer.py"
click node_agent_main "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/agent/main.py"
click node_agent_tools "https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/agent/tools.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_web,node_user toneBlue
class node_api,node_input_guard,node_output_guard,node_router,node_synthesis toneAmber
class node_search,node_index_data,node_transcriber,node_chunker,node_pipeline,node_embedder,node_chroma,node_preindexer toneMint
class node_agent_main,node_agent_tools toneRose
class node_llm toneIndigo
```

## Components

### User experience

- [Web interface](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/templates/index.html): `templates/index.html`

### Query and safeguards

- [FastAPI endpoints](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/api/index.py): `api/index.py`
- [Input checks](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/guardrails/input_guard.py): `src/guardrails/input_guard.py`
- [Output checks](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/guardrails/output_guard.py): `src/guardrails/output_guard.py`
- [Guardrail router](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/guardrails/router.py): `src/guardrails/router.py`
- [Answer synthesis](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/api/index.py): `api/index.py`

### Transcript knowledge

- [Hybrid transcript search](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/search.py): `src/ingestion/search.py`
- [Preindexed embeddings](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/data/preindexed_embeddings.json): `data/preindexed_embeddings.json`
- [Transcript parsing](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/transcriber.py): `src/ingestion/transcriber.py`
- [Timestamp chunking](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/chunker.py): `src/ingestion/chunker.py`
- [Ingestion pipeline](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/pipeline.py): `src/ingestion/pipeline.py`
- [Chroma indexing](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/embedder.py): `src/ingestion/embedder.py`
- [Chroma store](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/tree/main/data/chroma_db): `data/chroma_db`
- [Preindex generation](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/ingestion/preindexer.py): `src/ingestion/preindexer.py`

### Agent workflow

- [Agent entry point](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/agent/main.py): `src/agent/main.py`
- [Transcript search tool](https://github.com/muthukumar-selvarasu/video-rag-with-guardrails-evals/blob/main/src/agent/tools.py): `src/agent/tools.py`

### Other components

- **User**
- **LLM provider**

## Connections

- User → Web interface: asks questions (evidence: `README.md`)
- Web interface → FastAPI endpoints: sends requests (evidence: `README.md`)
- FastAPI endpoints → Input checks: checks query (evidence: `api/index.py`)
- FastAPI endpoints → Hybrid transcript search: retrieves passages (evidence: `api/index.py`)
- Hybrid transcript search → Preindexed embeddings: reads vectors (evidence: `README.md`)
- FastAPI endpoints → Answer synthesis: builds answer (evidence: `api/index.py`)
- Answer synthesis → LLM provider: requests synthesis (evidence: `README.md`)
- FastAPI endpoints → Output checks: checks response (evidence: `README.md`)
- FastAPI endpoints → Web interface: returns answer (evidence: `README.md`)
- Web interface → User: shows timestamps (evidence: `README.md`)
- FastAPI endpoints → Guardrail router: uses guarded flow (evidence: `api/index.py`)
- Guardrail router → Input checks: validates input (evidence: `src/guardrails/router.py`)
- Guardrail router → Output checks: validates output (evidence: `src/guardrails/router.py`)
- Ingestion pipeline → Transcript parsing: loads transcripts (evidence: `src/ingestion/pipeline.py`)
- Ingestion pipeline → Timestamp chunking: chunks transcripts (evidence: `src/ingestion/pipeline.py`)
- Ingestion pipeline → Chroma indexing: indexes chunks (evidence: `src/ingestion/pipeline.py`)
- Chroma indexing → Chroma store: writes chunks (evidence: `src/ingestion/embedder.py`)
- Preindex generation → Timestamp chunking: uses chunking (evidence: `src/ingestion/preindexer.py`)
- Agent entry point → Guardrail router: guards execution (evidence: `src/agent/main.py`)
- Agent entry point → Transcript search tool: registers tool (evidence: `src/agent/main.py`)
- Transcript search tool → Hybrid transcript search: queries transcripts (evidence: `src/agent/tools.py`)
- Agent entry point → LLM provider: configures agent
