# ankitporwal04/smart-llm-router architecture

> Architecture diagram of the GitHub repository ankitporwal04/smart-llm-router, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ankitporwal04/smart-llm-router
- Repository: https://github.com/ankitporwal04/smart-llm-router

## Overview

Smart LLM Router is a web app that classifies queries, selects a fast or powerful model, generates an answer, and reports cost and usage. The React interface submits queries and displays responses and live metrics; the FastAPI route delegates query handling to the routing engine. The engine owns classification, model selection, fallback, generation, and metric recording. README also documents heuristic, LLM, and hybrid classification, multi-provider support, health reporting, and browser session persistence. Edges reflect sampled calls or README-described behavior; unsampled UI and classifier internals are not expanded.

Main entry points: [`frontend/src/components/RouterPage.tsx`](https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/components/RouterPage.tsx) (Router page), [`app/api/dependencies.py`](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/api/dependencies.py) (Dependency wiring), [`app/router/router.py`](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/router/router.py) (Routing engine), [`app/api/routes.py`](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/api/routes.py) (HTTP endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_router_ui["Router page<br/>[RouterPage.tsx]"]
  node_query_form["Query form<br/>[QueryForm.tsx]"]
  node_response_card["Response display<br/>[ResponseCard.tsx]"]
  node_dashboard["Metrics dashboard"]
  node_web_api["API client<br/>[api.ts]"]
  node_session["Session history<br/>[RouterPage.tsx]"]
end

subgraph group_api["API service"]
  node_api_routes["HTTP endpoints<br/>[routes.py]"]
  node_dependencies["Dependency wiring<br/>[dependencies.py]"]
  node_request_models["Request and response schemas<br/>[models.py]"]
end

subgraph group_classification["Query classification"]
  node_classifier_base["Classifier contract<br/>[base.py]"]
  node_heuristic["Heuristic classifier<br/>[heuristic.py]"]
  node_llm_classifier["LLM classifier<br/>[llm_classifier.py]"]
  node_hybrid["Hybrid classifier<br/>[hybrid.py]"]
end

subgraph group_routing["Model routing"]
  node_router["Routing engine<br/>[router.py]"]
  node_llm_client["LLM generation client<br/>[openai_client.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_observability["Metrics and health"]
  node_collector["Cost and metric builder<br/>[collector.py]"]
  node_store[("Metrics store<br/>[store.py]")]
  node_health["Health status<br/>[routes.py]"]
end

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

node_user -->|"uses"| node_router_ui
node_router_ui -->|"renders"| node_query_form
node_router_ui -->|"submits queries"| node_web_api
node_web_api -->|"calls endpoints"| node_api_routes
node_api_routes -->|"delegates query"| node_router
node_api_routes -->|"reads summary"| node_store
node_dependencies -->|"constructs"| node_router
node_dependencies -->|"selects"| node_heuristic
node_dependencies -->|"selects"| node_hybrid
node_dependencies -->|"selects"| node_llm_classifier
node_dependencies -->|"constructs"| node_llm_client
node_dependencies -->|"provides"| node_store
node_api_routes -->|"injects"| node_dependencies
node_api_routes -->|"validates and returns"| node_request_models
node_router -->|"classifies with"| node_classifier_base
node_router -->|"generates response"| node_llm_client
node_router -->|"builds metrics"| node_collector
node_router -->|"records metrics"| node_store
node_router -->|"selects and falls back"| node_config
node_heuristic -->|"implements"| node_classifier_base
node_llm_classifier -->|"implements"| node_classifier_base
node_hybrid -->|"uses"| node_heuristic
node_hybrid -->|"uses"| node_llm_classifier
node_llm_client -->|"requests completion"| node_provider
node_llm_classifier -->|"classifies via"| node_provider
node_store -->|"aggregates metrics"| node_request_models
node_collector -->|"builds metric"| node_request_models
node_router_ui -->|"renders"| node_dashboard
node_router_ui -->|"renders responses"| node_response_card
node_router_ui -->|"persists history"| node_session
node_router_ui -->|"fetches metrics"| node_web_api
node_web_api -->|"requests metrics"| node_store
node_api_routes -->|"serves health"| node_health

click node_router_ui "https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/components/RouterPage.tsx"
click node_query_form "https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/components/QueryForm.tsx"
click node_response_card "https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/components/ResponseCard.tsx"
click node_dashboard "https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/components/MetricsDashboard.tsx"
click node_web_api "https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/api.ts"
click node_session "https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/components/RouterPage.tsx"
click node_api_routes "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/api/routes.py"
click node_dependencies "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/api/dependencies.py"
click node_request_models "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/models.py"
click node_classifier_base "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/classifier/base.py"
click node_heuristic "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/classifier/heuristic.py"
click node_llm_classifier "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/classifier/llm_classifier.py"
click node_hybrid "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/classifier/hybrid.py"
click node_router "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/router/router.py"
click node_llm_client "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/llm/openai_client.py"
click node_config "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/config.py"
click node_collector "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/metrics/collector.py"
click node_store "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/metrics/store.py"
click node_health "https://github.com/ankitporwal04/smart-llm-router/blob/main/app/api/routes.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_router_ui,node_query_form,node_response_card,node_dashboard,node_web_api,node_session,node_user toneBlue
class node_api_routes,node_dependencies,node_request_models toneAmber
class node_classifier_base,node_heuristic,node_llm_classifier,node_hybrid toneMint
class node_router,node_llm_client,node_config toneRose
class node_collector,node_store,node_health,node_provider toneIndigo
```

## Components

### Web interface

- [Router page](https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/components/RouterPage.tsx): `frontend/src/components/RouterPage.tsx`
- [Query form](https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/components/QueryForm.tsx): `frontend/src/components/QueryForm.tsx`
- [Response display](https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/components/ResponseCard.tsx): `frontend/src/components/ResponseCard.tsx`
- [Metrics dashboard](https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/components/MetricsDashboard.tsx): `frontend/src/components/MetricsDashboard.tsx`
- [API client](https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Session history](https://github.com/ankitporwal04/smart-llm-router/blob/main/frontend/src/components/RouterPage.tsx): `frontend/src/components/RouterPage.tsx`

### API service

- [HTTP endpoints](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/api/routes.py): `app/api/routes.py`
- [Dependency wiring](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/api/dependencies.py): `app/api/dependencies.py`
- [Request and response schemas](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/models.py): `app/models.py`

### Query classification

- [Classifier contract](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/classifier/base.py): `app/classifier/base.py`
- [Heuristic classifier](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/classifier/heuristic.py): `app/classifier/heuristic.py`
- [LLM classifier](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/classifier/llm_classifier.py): `app/classifier/llm_classifier.py`
- [Hybrid classifier](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/classifier/hybrid.py): `app/classifier/hybrid.py`

### Model routing

- [Routing engine](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/router/router.py): `app/router/router.py`
- [LLM generation client](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/llm/openai_client.py): `app/llm/openai_client.py`
- [Runtime settings](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/config.py): `app/config.py`

### Metrics and health

- [Cost and metric builder](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/metrics/collector.py): `app/metrics/collector.py`
- [Metrics store](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/metrics/store.py): `app/metrics/store.py`
- [Health status](https://github.com/ankitporwal04/smart-llm-router/blob/main/app/api/routes.py): `app/api/routes.py`

### Other components

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

## Connections

- User → Router page: uses (evidence: `README.md`)
- Router page → Query form: renders (evidence: `frontend/src/components/RouterPage.tsx`)
- Router page → API client: submits queries (evidence: `frontend/src/components/RouterPage.tsx`)
- API client → HTTP endpoints: calls endpoints (evidence: `README.md`)
- HTTP endpoints → Routing engine: delegates query (evidence: `app/api/routes.py`)
- HTTP endpoints → Metrics store: reads summary (evidence: `app/api/routes.py`)
- Dependency wiring → Routing engine: constructs (evidence: `app/api/dependencies.py`)
- Dependency wiring → Heuristic classifier: selects (evidence: `app/api/dependencies.py`)
- Dependency wiring → Hybrid classifier: selects (evidence: `app/api/dependencies.py`)
- Dependency wiring → LLM classifier: selects (evidence: `app/api/dependencies.py`)
- Dependency wiring → LLM generation client: constructs (evidence: `app/api/dependencies.py`)
- Dependency wiring → Metrics store: provides (evidence: `app/api/dependencies.py`)
- HTTP endpoints → Dependency wiring: injects (evidence: `app/api/routes.py`)
- HTTP endpoints → Request and response schemas: validates and returns (evidence: `app/api/routes.py`)
- Routing engine → Classifier contract: classifies with (evidence: `app/router/router.py`)
- Routing engine → LLM generation client: generates response (evidence: `app/router/router.py`)
- Routing engine → Cost and metric builder: builds metrics (evidence: `app/router/router.py`)
- Routing engine → Metrics store: records metrics (evidence: `app/router/router.py`)
- Routing engine → Runtime settings: selects and falls back (evidence: `app/router/router.py`)
- Heuristic classifier → Classifier contract: implements (evidence: `app/classifier/heuristic.py`)
- LLM classifier → Classifier contract: implements (evidence: `app/classifier/llm_classifier.py`)
- Hybrid classifier → Heuristic classifier: uses (evidence: `app/classifier/hybrid.py`)
- Hybrid classifier → LLM classifier: uses (evidence: `app/classifier/hybrid.py`)
- LLM generation client → LLM provider: requests completion (evidence: `app/llm/openai_client.py`)
- LLM classifier → LLM provider: classifies via (evidence: `app/classifier/llm_classifier.py`)
- Metrics store → Request and response schemas: aggregates metrics (evidence: `app/metrics/store.py`)
- Cost and metric builder → Request and response schemas: builds metric (evidence: `app/router/router.py`)
- Router page → Metrics dashboard: renders (evidence: `frontend/src/components/RouterPage.tsx`)
- Router page → Response display: renders responses (evidence: `frontend/src/components/RouterPage.tsx`)
- Router page → Session history: persists history (evidence: `frontend/src/components/RouterPage.tsx`)
- Router page → API client: fetches metrics (evidence: `frontend/src/components/RouterPage.tsx`)
- API client → Metrics store: requests metrics (evidence: `README.md`)
- HTTP endpoints → Health status: serves health (evidence: `app/api/routes.py`)
