# sourangshupal/8hr-marathon architecture

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

- Interactive diagram: https://gitdiagram.com/sourangshupal/8hr-marathon
- Repository: https://github.com/sourangshupal/8hr-marathon

## Overview

Enterprise Agentic RAG accepts user questions through a Streamlit chat or the API, applies guardrails, then runs a LangGraph planner that either answers conversationally or retrieves technical context before generating a response. Document ingestion parses local files, chunks text, embeds it, and indexes it for later search. The product also exposes health and metrics endpoints and includes a separate RAGAS evaluation suite. Edges reflect the excerpts, SOURCE INDEX references, and README; some documented capabilities, including API protection and observability, have no sampled implementation detail.

Main entry points: [`app/agents/graph.py`](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/graph.py) (LangGraph workflow), [`app/main.py`](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/main.py) (FastAPI API), [`app/ingestion/processor.py`](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/ingestion/processor.py) (Ingestion processor), [`evals/app.py`](https://github.com/sourangshupal/8hr-marathon/blob/deployment/evals/app.py) (Evaluation demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and UI"]
  node_ui["Streamlit chat<br/>[app.py]"]
  node_api_service["FastAPI API<br/>[main.py]"]
  node_guardrails["Input/output rails<br/>[rails.py]"]
  node_health["Health checks<br/>[health.py]"]
  node_metrics["Prometheus metrics<br/>[main.py]"]
end

subgraph group_agent["Agent workflow"]
  node_graph["LangGraph workflow<br/>[graph.py]"]
  node_state["Conversation state<br/>[state.py]"]
  node_planner["Query planner<br/>[planner.py]"]
  node_retriever["Technical retriever<br/>[retriever.py]"]
  node_responder["Answer generator<br/>[responder.py]"]
end

subgraph group_knowledge["Knowledge indexing"]
  node_ingest["Ingestion processor<br/>[processor.py]"]
  node_loaders["Document loaders"]
  node_splitter["Text chunker<br/>[splitter.py]"]
end

subgraph group_infra["Stores and integrations"]
  node_gateway["Portkey LLM client<br/>[client.py]"]
  node_memory[("Checkpoint store<br/>[graph.py]")]
  node_qdrant[("Qdrant vector store<br/>[qdrant_service.py]")]
  node_embedding["Embedding service<br/>[embedding.py]"]
  node_ranker["Semantic reranker<br/>[ranking_service.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_app["Evaluation demo<br/>[app.py]"]
  node_eval_pipeline["Live pipeline eval<br/>[pipeline.py]"]
  node_eval_metrics["RAGAS metrics<br/>[metrics.py]"]
  node_eval_guardrails["Guardrails eval<br/>[guardrails_eval.py]"]
end

node_user(("User"))
node_jina["Jina embedding API"]
node_jina_ranker["Jina reranker API"]

node_user -->|"asks via"| node_ui
node_ui -->|"submits query"| node_api_service
node_api_service -->|"filters input"| node_guardrails
node_api_service -->|"invokes workflow"| node_graph
node_api_service -->|"exposes metrics"| node_metrics
node_api_service -->|"serves health"| node_health
node_graph -->|"dispatches"| node_planner
node_graph -->|"routes technical"| node_retriever
node_graph -->|"routes conversational"| node_responder
node_graph -->|"routes retrieved"| node_responder
node_graph -->|"checkpoints state"| node_memory
node_planner -->|"calls LLM"| node_gateway
node_responder -->|"calls LLM"| node_gateway
node_retriever -->|"searches vectors"| node_qdrant
node_retriever -->|"reranks results"| node_ranker
node_qdrant -->|"embeds query"| node_embedding
node_embedding -.->|"requests embeddings"| node_jina
node_ranker -->|"requests ranking"| node_jina_ranker
node_ingest -->|"parses files"| node_loaders
node_ingest -->|"chunks text"| node_splitter
node_ingest -->|"embeds chunks"| node_embedding
node_ingest -->|"indexes vectors"| node_qdrant
node_eval_app -->|"runs pipeline"| node_eval_pipeline
node_eval_app -->|"computes metrics"| node_eval_metrics
node_eval_app -->|"evaluates rails"| node_eval_guardrails
node_eval_pipeline -->|"queries endpoint"| node_api_service

click node_ui "https://github.com/sourangshupal/8hr-marathon/blob/deployment/ui/app.py"
click node_api_service "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/main.py"
click node_guardrails "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/guardrails/rails.py"
click node_health "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/health.py"
click node_metrics "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/main.py"
click node_graph "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/graph.py"
click node_state "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/state.py"
click node_planner "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/nodes/planner.py"
click node_retriever "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/nodes/retriever.py"
click node_responder "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/nodes/responder.py"
click node_gateway "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/gateway/client.py"
click node_memory "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/graph.py"
click node_qdrant "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/services/retrieval/qdrant_service.py"
click node_embedding "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/services/retrieval/embedding.py"
click node_ranker "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/services/retrieval/ranking_service.py"
click node_ingest "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/ingestion/processor.py"
click node_loaders "https://github.com/sourangshupal/8hr-marathon/tree/deployment/app/ingestion/loaders"
click node_splitter "https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/ingestion/chunking/splitter.py"
click node_eval_app "https://github.com/sourangshupal/8hr-marathon/blob/deployment/evals/app.py"
click node_eval_pipeline "https://github.com/sourangshupal/8hr-marathon/blob/deployment/evals/pipeline.py"
click node_eval_metrics "https://github.com/sourangshupal/8hr-marathon/blob/deployment/evals/metrics.py"
click node_eval_guardrails "https://github.com/sourangshupal/8hr-marathon/blob/deployment/evals/guardrails_eval.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_ui,node_api_service,node_guardrails,node_health,node_metrics,node_user toneBlue
class node_graph,node_state,node_planner,node_retriever,node_responder toneAmber
class node_ingest,node_loaders,node_splitter,node_jina,node_jina_ranker toneMint
class node_gateway,node_memory,node_qdrant,node_embedding,node_ranker toneRose
class node_eval_app,node_eval_pipeline,node_eval_metrics,node_eval_guardrails toneIndigo
```

## Components

### API and UI

- [Streamlit chat](https://github.com/sourangshupal/8hr-marathon/blob/deployment/ui/app.py): `ui/app.py`
- [FastAPI API](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/main.py): `app/main.py`
- [Input/output rails](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/guardrails/rails.py): `app/guardrails/rails.py`
- [Health checks](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/health.py): `app/health.py`
- [Prometheus metrics](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/main.py): `app/main.py`

### Agent workflow

- [LangGraph workflow](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/graph.py): `app/agents/graph.py`
- [Conversation state](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/state.py): `app/agents/state.py`
- [Query planner](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/nodes/planner.py): `app/agents/nodes/planner.py`
- [Technical retriever](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/nodes/retriever.py): `app/agents/nodes/retriever.py`
- [Answer generator](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/nodes/responder.py): `app/agents/nodes/responder.py`

### Knowledge indexing

- [Ingestion processor](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/ingestion/processor.py): `app/ingestion/processor.py`
- [Document loaders](https://github.com/sourangshupal/8hr-marathon/tree/deployment/app/ingestion/loaders): `app/ingestion/loaders`
- [Text chunker](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/ingestion/chunking/splitter.py): `app/ingestion/chunking/splitter.py`

### Stores and integrations

- [Portkey LLM client](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/gateway/client.py): `app/gateway/client.py`
- [Checkpoint store](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/agents/graph.py): `app/agents/graph.py`
- [Qdrant vector store](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/services/retrieval/qdrant_service.py): `app/services/retrieval/qdrant_service.py`
- [Embedding service](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/services/retrieval/embedding.py): `app/services/retrieval/embedding.py`
- [Semantic reranker](https://github.com/sourangshupal/8hr-marathon/blob/deployment/app/services/retrieval/ranking_service.py): `app/services/retrieval/ranking_service.py`

### Evaluation

- [Evaluation demo](https://github.com/sourangshupal/8hr-marathon/blob/deployment/evals/app.py): `evals/app.py`
- [Live pipeline eval](https://github.com/sourangshupal/8hr-marathon/blob/deployment/evals/pipeline.py): `evals/pipeline.py`
- [RAGAS metrics](https://github.com/sourangshupal/8hr-marathon/blob/deployment/evals/metrics.py): `evals/metrics.py`
- [Guardrails eval](https://github.com/sourangshupal/8hr-marathon/blob/deployment/evals/guardrails_eval.py): `evals/guardrails_eval.py`

### Other components

- **User**
- **Jina embedding API**
- **Jina reranker API**

## Connections

- User → Streamlit chat: asks via (evidence: `README.md`)
- Streamlit chat → FastAPI API: submits query (evidence: `README.md`)
- FastAPI API → Input/output rails: filters input (evidence: `README.md`)
- FastAPI API → LangGraph workflow: invokes workflow (evidence: `app/main.py`)
- FastAPI API → Prometheus metrics: exposes metrics (evidence: `README.md`)
- FastAPI API → Health checks: serves health (evidence: `app/main.py`)
- LangGraph workflow → Query planner: dispatches (evidence: `app/agents/graph.py`)
- LangGraph workflow → Technical retriever: routes technical (evidence: `app/agents/graph.py`)
- LangGraph workflow → Answer generator: routes conversational (evidence: `app/agents/graph.py`)
- LangGraph workflow → Answer generator: routes retrieved (evidence: `app/agents/graph.py`)
- LangGraph workflow → Checkpoint store: checkpoints state (evidence: `app/agents/graph.py`)
- Query planner → Portkey LLM client: calls LLM (evidence: `app/agents/nodes/planner.py`)
- Answer generator → Portkey LLM client: calls LLM (evidence: `app/agents/nodes/responder.py`)
- Technical retriever → Qdrant vector store: searches vectors (evidence: `app/agents/nodes/retriever.py`)
- Technical retriever → Semantic reranker: reranks results (evidence: `app/agents/nodes/retriever.py`)
- Qdrant vector store → Embedding service: embeds query (evidence: `app/services/retrieval/qdrant_service.py`)
- Embedding service → Jina embedding API: requests embeddings (evidence: `app/services/retrieval/embedding.py`)
- Semantic reranker → Jina reranker API: requests ranking (evidence: `app/services/retrieval/ranking_service.py`)
- Ingestion processor → Document loaders: parses files (evidence: `app/ingestion/processor.py`)
- Ingestion processor → Text chunker: chunks text (evidence: `app/ingestion/processor.py`)
- Ingestion processor → Embedding service: embeds chunks (evidence: `app/ingestion/processor.py`)
- Ingestion processor → Qdrant vector store: indexes vectors (evidence: `app/ingestion/processor.py`)
- Evaluation demo → Live pipeline eval: runs pipeline (evidence: `evals/app.py`)
- Evaluation demo → RAGAS metrics: computes metrics (evidence: `evals/app.py`)
- Evaluation demo → Guardrails eval: evaluates rails (evidence: `evals/app.py`)
- Live pipeline eval → FastAPI API: queries endpoint (evidence: `evals/pipeline.py`)
