# samarth40/rag-price-control architecture

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

- Interactive diagram: https://gitdiagram.com/samarth40/rag-price-control
- Repository: https://github.com/samarth40/rag-price-control

## Overview

This is a tenant-scoped RAG cost-control service: queries enter through the API, may fetch context from an existing RAG backend, then use semantic caching and model routing before returning an answer. Fresh requests are logged and cached; the dashboard displays query results and aggregate metrics. The README also describes BM25-plus-vector tiered retrieval, but the sampled BM25 implementation is not wired into the query orchestrator, so that branch is shown separately.

Main entry points: [`app/services/orchestrator.py`](https://github.com/samarth40/rag-price-control/blob/main/app/services/orchestrator.py) (Query Orchestrator), [`app/main.py`](https://github.com/samarth40/rag-price-control/blob/main/app/main.py) (FastAPI Service), [`streamlit_app.py`](https://github.com/samarth40/rag-price-control/blob/main/streamlit_app.py) (Streamlit Dashboard), [`app/services/semantic_cache.py`](https://github.com/samarth40/rag-price-control/blob/main/app/services/semantic_cache.py) (Semantic Cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_dashboard["Streamlit Dashboard<br/>[streamlit_app.py]"]
  node_api["FastAPI Service<br/>[main.py]"]
end

subgraph group_runtime["Query Runtime"]
  node_orchestrator["Query Orchestrator<br/>[orchestrator.py]"]
  node_cache["Semantic Cache<br/>[semantic_cache.py]"]
  node_redis[("Redis Cache Store")]
  node_router["Model Router<br/>[model_router.py]"]
  node_cheap_model["Economical Model"]
  node_strong_model["Strong Model"]
end

subgraph group_retrieval["Retrieval"]
  node_bm25["BM25 Prefilter"]
  node_vector_search["Vector Search"]
end

subgraph group_observability["Observability"]
  node_events["Event Logging<br/>[observability.py]"]
  node_event_db[("SQLite Events")]
  node_metrics["Stats Summary<br/>[observability.py]"]
end

node_user(("User"))
node_rag_backend["Existing RAG Backend"]

node_user -->|"uses"| node_dashboard
node_dashboard -->|"submits query"| node_api
node_dashboard -->|"requests stats"| node_api
node_api -->|"runs query"| node_orchestrator
node_api -->|"gets summary"| node_metrics
node_orchestrator -.->|"fetches context"| node_rag_backend
node_rag_backend -.->|"returns chunks"| node_orchestrator
node_orchestrator -->|"looks up and stores"| node_cache
node_cache -->|"reads and writes"| node_redis
node_orchestrator -->|"classifies query"| node_router
node_router -->|"returns route"| node_orchestrator
node_orchestrator -->|"calls model"| node_cheap_model
node_orchestrator -->|"escalates when unsure"| node_strong_model
node_orchestrator -->|"logs request"| node_events
node_events -->|"writes events"| node_event_db
node_metrics -->|"queries events"| node_event_db
node_bm25 -.->|"candidate IDs for reranking"| node_vector_search

click node_dashboard "https://github.com/samarth40/rag-price-control/blob/main/streamlit_app.py"
click node_api "https://github.com/samarth40/rag-price-control/blob/main/app/main.py"
click node_orchestrator "https://github.com/samarth40/rag-price-control/blob/main/app/services/orchestrator.py"
click node_cache "https://github.com/samarth40/rag-price-control/blob/main/app/services/semantic_cache.py"
click node_router "https://github.com/samarth40/rag-price-control/blob/main/app/services/model_router.py"
click node_bm25 "https://github.com/samarth40/rag-price-control/blob/main/app/services/tiered_retrieval.py"
click node_events "https://github.com/samarth40/rag-price-control/blob/main/app/core/observability.py"
click node_metrics "https://github.com/samarth40/rag-price-control/blob/main/app/core/observability.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_dashboard,node_api,node_user toneBlue
class node_orchestrator,node_cache,node_redis,node_router,node_cheap_model,node_strong_model toneAmber
class node_bm25,node_vector_search toneMint
class node_events,node_event_db,node_metrics toneRose
class node_rag_backend toneIndigo
```

## Components

### User Interfaces

- [Streamlit Dashboard](https://github.com/samarth40/rag-price-control/blob/main/streamlit_app.py): `streamlit_app.py`
- [FastAPI Service](https://github.com/samarth40/rag-price-control/blob/main/app/main.py): `app/main.py`

### Query Runtime

- [Query Orchestrator](https://github.com/samarth40/rag-price-control/blob/main/app/services/orchestrator.py): `app/services/orchestrator.py`
- [Semantic Cache](https://github.com/samarth40/rag-price-control/blob/main/app/services/semantic_cache.py): `app/services/semantic_cache.py`
- **Redis Cache Store**
- [Model Router](https://github.com/samarth40/rag-price-control/blob/main/app/services/model_router.py): `app/services/model_router.py`
- **Economical Model**
- **Strong Model**

### Retrieval

- [BM25 Prefilter](https://github.com/samarth40/rag-price-control/blob/main/app/services/tiered_retrieval.py): `app/services/tiered_retrieval.py`
- **Vector Search**

### Observability

- [Event Logging](https://github.com/samarth40/rag-price-control/blob/main/app/core/observability.py): `app/core/observability.py`
- **SQLite Events**
- [Stats Summary](https://github.com/samarth40/rag-price-control/blob/main/app/core/observability.py): `app/core/observability.py`

### Other components

- **User**
- **Existing RAG Backend**

## Connections

- User → Streamlit Dashboard: uses
- Streamlit Dashboard → FastAPI Service: submits query
- Streamlit Dashboard → FastAPI Service: requests stats
- FastAPI Service → Query Orchestrator: runs query
- FastAPI Service → Stats Summary: gets summary
- Query Orchestrator → Existing RAG Backend: fetches context
- Existing RAG Backend → Query Orchestrator: returns chunks
- Query Orchestrator → Semantic Cache: looks up and stores
- Semantic Cache → Redis Cache Store: reads and writes
- Query Orchestrator → Model Router: classifies query
- Model Router → Query Orchestrator: returns route
- Query Orchestrator → Economical Model: calls model
- Query Orchestrator → Strong Model: escalates when unsure
- Query Orchestrator → Event Logging: logs request
- Event Logging → SQLite Events: writes events
- Stats Summary → SQLite Events: queries events
- BM25 Prefilter → Vector Search: candidate IDs for reranking