# rajdeepofgithub/query-router architecture

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

- Interactive diagram: https://gitdiagram.com/rajdeepofgithub/query-router
- Repository: https://github.com/rajdeepofgithub/query-router

## Overview

Query Router classifies JPMorgan Chase questions as SQL, RAG, or both, then executes the selected backend path and returns an answer; combined answers add disclosures, citations, and conflict handling. Its evaluation workflows measure routing alone and end-to-end answer quality against separate truth data, while shared instrumentation records API usage and cost. The README documents backend stages and integrations that are outside this repository; those are shown as external systems, not as inspected source modules.

Main entry points: [`src/router.py`](https://github.com/rajdeepofgithub/query-router/blob/main/src/router.py) (Answer entry point), [`src/execute.py`](https://github.com/rajdeepofgithub/query-router/blob/main/src/execute.py) (Route executor), [`src/run_router_eval.py`](https://github.com/rajdeepofgithub/query-router/blob/main/src/run_router_eval.py) (End-to-end evaluator), [`src/run_routing_eval.py`](https://github.com/rajdeepofgithub/query-router/blob/main/src/run_routing_eval.py) (Routing evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["Routing"]
  node_classifier["Route classifier<br/>[classify.py]"]
  node_router["Answer entry point<br/>[router.py]"]
end

subgraph group_execution["Execution"]
  node_executor["Route executor<br/>[execute.py]"]
  node_sql_backend["Text-to-SQL"]
  node_rag_backend["Financial RAG"]
  node_merger["Answer merger<br/>[execute.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_routing_data["Routing questions<br/>[routing_eval.jsonl]"]
  node_answer_truth["Answer truth data"]
  node_routing_eval["Routing evaluator"]
  node_e2e_eval["End-to-end evaluator<br/>[run_router_eval.py]"]
  node_baseline["Evaluation results"]
end

subgraph group_observability["Observability"]
  node_cost_tracker["API cost tracker<br/>[costs.py]"]
end

node_analyst(("Question asker"))
node_openai["OpenAI API"]

node_analyst -->|"asks question"| node_router
node_router -->|"classifies"| node_classifier
node_router -->|"executes route"| node_executor
node_executor -->|"runs SQL"| node_sql_backend
node_executor -->|"runs retrieval"| node_rag_backend
node_executor -->|"merges both"| node_merger
node_routing_data -->|"supplies questions"| node_routing_eval
node_routing_eval -->|"classifies"| node_classifier
node_routing_eval -->|"writes results"| node_baseline
node_routing_data -->|"supplies questions"| node_e2e_eval
node_answer_truth -->|"supplies grading truth"| node_e2e_eval
node_e2e_eval -->|"runs answer"| node_router
node_e2e_eval -->|"grades outputs"| node_executor
node_e2e_eval -->|"writes results"| node_baseline
node_router -->|"labels usage"| node_cost_tracker
node_cost_tracker -->|"wraps API calls"| node_openai
node_classifier -->|"requests classification"| node_openai

click node_classifier "https://github.com/rajdeepofgithub/query-router/blob/main/src/classify.py"
click node_router "https://github.com/rajdeepofgithub/query-router/blob/main/src/router.py"
click node_executor "https://github.com/rajdeepofgithub/query-router/blob/main/src/execute.py"
click node_merger "https://github.com/rajdeepofgithub/query-router/blob/main/src/execute.py"
click node_routing_data "https://github.com/rajdeepofgithub/query-router/blob/main/data/routing_eval.jsonl"
click node_answer_truth "https://github.com/rajdeepofgithub/query-router/blob/main/data/router_answer_truth.jsonl"
click node_routing_eval "https://github.com/rajdeepofgithub/query-router/blob/main/src/run_routing_eval.py"
click node_e2e_eval "https://github.com/rajdeepofgithub/query-router/blob/main/src/run_router_eval.py"
click node_baseline "https://github.com/rajdeepofgithub/query-router/tree/main/baseline"
click node_cost_tracker "https://github.com/rajdeepofgithub/query-router/blob/main/src/costs.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_classifier,node_router toneBlue
class node_executor,node_sql_backend,node_rag_backend,node_merger toneAmber
class node_routing_data,node_answer_truth,node_routing_eval,node_e2e_eval,node_baseline,node_openai toneMint
class node_cost_tracker toneRose
class node_analyst toneIndigo
```

## Components

### Routing

- [Route classifier](https://github.com/rajdeepofgithub/query-router/blob/main/src/classify.py): `src/classify.py`
- [Answer entry point](https://github.com/rajdeepofgithub/query-router/blob/main/src/router.py): `src/router.py`

### Execution

- [Route executor](https://github.com/rajdeepofgithub/query-router/blob/main/src/execute.py): `src/execute.py`
- **Text-to-SQL**
- **Financial RAG**
- [Answer merger](https://github.com/rajdeepofgithub/query-router/blob/main/src/execute.py): `src/execute.py`

### Evaluation

- [Routing questions](https://github.com/rajdeepofgithub/query-router/blob/main/data/routing_eval.jsonl): `data/routing_eval.jsonl`
- [Answer truth data](https://github.com/rajdeepofgithub/query-router/blob/main/data/router_answer_truth.jsonl): `data/router_answer_truth.jsonl`
- [Routing evaluator](https://github.com/rajdeepofgithub/query-router/blob/main/src/run_routing_eval.py): `src/run_routing_eval.py`
- [End-to-end evaluator](https://github.com/rajdeepofgithub/query-router/blob/main/src/run_router_eval.py): `src/run_router_eval.py`
- [Evaluation results](https://github.com/rajdeepofgithub/query-router/tree/main/baseline): `baseline`

### Observability

- [API cost tracker](https://github.com/rajdeepofgithub/query-router/blob/main/src/costs.py): `src/costs.py`

### Other components

- **Question asker**
- **OpenAI API**

## Connections

- Question asker → Answer entry point: asks question (evidence: `README.md`)
- Answer entry point → Route classifier: classifies (evidence: `src/router.py`)
- Answer entry point → Route executor: executes route (evidence: `src/router.py`)
- Route executor → Text-to-SQL: runs SQL (evidence: `README.md`)
- Route executor → Financial RAG: runs retrieval (evidence: `README.md`)
- Route executor → Answer merger: merges both (evidence: `src/execute.py`)
- Routing questions → Routing evaluator: supplies questions (evidence: `src/run_routing_eval.py`)
- Routing evaluator → Route classifier: classifies (evidence: `src/run_routing_eval.py`)
- Routing evaluator → Evaluation results: writes results (evidence: `src/run_routing_eval.py`)
- Routing questions → End-to-end evaluator: supplies questions (evidence: `src/run_router_eval.py`)
- Answer truth data → End-to-end evaluator: supplies grading truth (evidence: `src/run_router_eval.py`)
- End-to-end evaluator → Answer entry point: runs answer (evidence: `src/run_router_eval.py`)
- End-to-end evaluator → Route executor: grades outputs (evidence: `src/run_router_eval.py`)
- End-to-end evaluator → Evaluation results: writes results (evidence: `src/run_router_eval.py`)
- Answer entry point → API cost tracker: labels usage (evidence: `src/router.py`)
- API cost tracker → OpenAI API: wraps API calls (evidence: `src/costs.py`)
- Route classifier → OpenAI API: requests classification (evidence: `src/classify.py`)