# sandesh339/gtfs_idea architecture

> Architecture diagram of the GitHub repository sandesh339/gtfs_idea, 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/sandesh339/gtfs_idea
- Repository: https://github.com/sandesh339/gtfs_idea

## Overview

The product is a GTFS feed-editing chatbot with a web workspace, plus a controlled benchmark comparing function-calling and code-generation edits. The main flow is upload or load a feed, route a request to lookup, clarification, function calling, or code generation, then validate and present the result. The graph also preserves the documented benchmark and session-persistence branches. Some implementation files were not sampled; their links are included only where the SOURCE INDEX or README supports them.

Main entry points: [`frontend/src/App.jsx`](https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/App.jsx) (Chat and views), [`server/app.py`](https://github.com/sandesh339/gtfs_idea/blob/main/server/app.py) (FastAPI routes), [`gtfs_tools/chat.py`](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/chat.py) (Chat orchestration), [`run_benchmark.py`](https://github.com/sandesh339/gtfs_idea/blob/main/run_benchmark.py) (FC vs codegen benchmark)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web workspace"]
  node_workspace["Chat and views<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_chat_panel["Chat panel<br/>[ChatPanel.jsx]"]
  node_feed_views["Map, tables, diff<br/>[MapView.jsx]"]
  node_validation_view["Validation view<br/>[ValidationView.jsx]"]
  node_pyodide["Browser code runner<br/>[pyodideRunner.js]"]
end

subgraph group_backend["Sessions and API"]
  node_http_api["FastAPI routes<br/>[app.py]"]
  node_session_store["Session lifecycle<br/>[sessions.py]"]
  node_storage[("Session storage<br/>[storage.py]")]
  node_auth["Request authorization<br/>[auth.py]"]
end

subgraph group_editing["GTFS editing"]
  node_chat_session["Chat orchestration<br/>[chat.py]"]
  node_router["Request router<br/>[router.py]"]
  node_query["Read-only lookup<br/>[query.py]"]
  node_fc_executor["Function-call executor<br/>[executor.py]"]
  node_codegen["Code generation<br/>[codegen.py]"]
  node_toolkit["GTFS tools<br/>[tools.py]"]
  node_feed["GTFS feed model<br/>[feed.py]"]
end

subgraph group_grading["Benchmark and grading"]
  node_scenario_set["Benchmark scenarios"]
  node_scenario_runner["Scenario runner<br/>[scenarios.py]"]
  node_benchmark["FC vs codegen benchmark<br/>[run_benchmark.py]"]
  node_oracle["Expected outcomes<br/>[oracle.py]"]
  node_grader["Outcome grading<br/>[grader.py]"]
  node_diffing["Entity-level diff<br/>[diffing.py]"]
  node_validator["GTFS validation<br/>[gtfs_validator.py]"]
end

subgraph group_integrations["External services"]
  node_llm["LLM client<br/>[llm.py]"]
  node_official_validator["Official validator<br/>[app.py]"]
end

node_user(("Transit editor"))

node_user -->|"edits feed"| node_workspace
node_workspace -->|"calls API"| node_api_client
node_workspace -->|"renders"| node_chat_panel
node_workspace -->|"renders"| node_feed_views
node_workspace -->|"renders"| node_validation_view
node_workspace -->|"runs code"| node_pyodide
node_api_client -.->|"sends requests"| node_http_api
node_http_api -->|"protects routes"| node_auth
node_http_api -->|"loads sessions"| node_session_store
node_http_api -->|"configures backend"| node_storage
node_session_store -->|"persists state"| node_storage
node_session_store -->|"reconstructs chat"| node_chat_session
node_http_api -->|"handles requests"| node_chat_session
node_http_api -->|"validates feeds"| node_validator
node_workspace -.->|"commits feed"| node_http_api
node_chat_session -->|"routes request"| node_router
node_chat_session -->|"dispatches lookup"| node_query
node_chat_session -->|"dispatches edits"| node_fc_executor
node_chat_session -->|"dispatches generation"| node_codegen
node_chat_session -->|"computes changes"| node_diffing
node_router -->|"requests decision"| node_llm
node_query -->|"dispatches read tools"| node_toolkit
node_query -->|"runs lookup loop"| node_llm
node_fc_executor -->|"dispatches tools"| node_toolkit
node_fc_executor -->|"requests tool calls"| node_llm
node_codegen -->|"generates program"| node_llm
node_fc_executor -->|"edits feed"| node_feed
node_toolkit -->|"reads and edits"| node_feed
node_codegen -->|"edits feed"| node_feed
node_workspace -->|"executes generated code"| node_pyodide
node_scenario_runner -->|"loads scenarios"| node_scenario_set
node_benchmark -->|"loads cases"| node_scenario_set
node_benchmark -->|"runs FC edits"| node_fc_executor
node_benchmark -->|"runs generated edits"| node_codegen
node_benchmark -->|"uses answer keys"| node_oracle
node_benchmark -->|"measures changes"| node_diffing
node_scenario_runner -->|"grades scenarios"| node_grader
node_grader -->|"measures damage"| node_diffing
node_grader -->|"checks validity"| node_validator
node_grader -.->|"checks correctness"| node_oracle
node_grader -.->|"optional validation"| node_official_validator

click node_workspace "https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/api.js"
click node_chat_panel "https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/components/ChatPanel.jsx"
click node_feed_views "https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/components/MapView.jsx"
click node_validation_view "https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/components/ValidationView.jsx"
click node_pyodide "https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/lib/pyodideRunner.js"
click node_http_api "https://github.com/sandesh339/gtfs_idea/blob/main/server/app.py"
click node_session_store "https://github.com/sandesh339/gtfs_idea/blob/main/server/sessions.py"
click node_storage "https://github.com/sandesh339/gtfs_idea/blob/main/server/storage.py"
click node_auth "https://github.com/sandesh339/gtfs_idea/blob/main/server/auth.py"
click node_chat_session "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/chat.py"
click node_router "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/router.py"
click node_query "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/query.py"
click node_fc_executor "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/executor.py"
click node_codegen "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/codegen.py"
click node_toolkit "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/tools.py"
click node_feed "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/feed.py"
click node_llm "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/llm.py"
click node_scenario_set "https://github.com/sandesh339/gtfs_idea/blob/main/benchmark_scenarios.py"
click node_scenario_runner "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/scenarios.py"
click node_benchmark "https://github.com/sandesh339/gtfs_idea/blob/main/run_benchmark.py"
click node_oracle "https://github.com/sandesh339/gtfs_idea/blob/main/oracle.py"
click node_grader "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/grader.py"
click node_diffing "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/diffing.py"
click node_validator "https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/gtfs_validator.py"
click node_official_validator "https://github.com/sandesh339/gtfs_idea/blob/main/validator-service/app.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_workspace,node_api_client,node_chat_panel,node_feed_views,node_validation_view,node_pyodide toneBlue
class node_http_api,node_session_store,node_storage,node_auth toneAmber
class node_chat_session,node_router,node_query,node_fc_executor,node_codegen,node_toolkit,node_feed toneMint
class node_scenario_set,node_scenario_runner,node_benchmark,node_oracle,node_grader,node_diffing,node_validator toneRose
class node_llm,node_official_validator,node_user toneIndigo
```

## Components

### Web workspace

- [Chat and views](https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Chat panel](https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/components/ChatPanel.jsx): `frontend/src/components/ChatPanel.jsx`
- [Map, tables, diff](https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/components/MapView.jsx): `frontend/src/components/MapView.jsx`
- [Validation view](https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/components/ValidationView.jsx): `frontend/src/components/ValidationView.jsx`
- [Browser code runner](https://github.com/sandesh339/gtfs_idea/blob/main/frontend/src/lib/pyodideRunner.js): `frontend/src/lib/pyodideRunner.js`

### Sessions and API

- [FastAPI routes](https://github.com/sandesh339/gtfs_idea/blob/main/server/app.py): `server/app.py`
- [Session lifecycle](https://github.com/sandesh339/gtfs_idea/blob/main/server/sessions.py): `server/sessions.py`
- [Session storage](https://github.com/sandesh339/gtfs_idea/blob/main/server/storage.py): `server/storage.py`
- [Request authorization](https://github.com/sandesh339/gtfs_idea/blob/main/server/auth.py): `server/auth.py`

### GTFS editing

- [Chat orchestration](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/chat.py): `gtfs_tools/chat.py`
- [Request router](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/router.py): `gtfs_tools/router.py`
- [Read-only lookup](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/query.py): `gtfs_tools/query.py`
- [Function-call executor](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/executor.py): `gtfs_tools/executor.py`
- [Code generation](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/codegen.py): `gtfs_tools/codegen.py`
- [GTFS tools](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/tools.py): `gtfs_tools/tools.py`
- [GTFS feed model](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/feed.py): `gtfs_tools/feed.py`

### Benchmark and grading

- [Benchmark scenarios](https://github.com/sandesh339/gtfs_idea/blob/main/benchmark_scenarios.py): `benchmark_scenarios.py`
- [Scenario runner](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/scenarios.py): `gtfs_tools/scenarios.py`
- [FC vs codegen benchmark](https://github.com/sandesh339/gtfs_idea/blob/main/run_benchmark.py): `run_benchmark.py`
- [Expected outcomes](https://github.com/sandesh339/gtfs_idea/blob/main/oracle.py): `oracle.py`
- [Outcome grading](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/grader.py): `gtfs_tools/grader.py`
- [Entity-level diff](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/diffing.py): `gtfs_tools/diffing.py`
- [GTFS validation](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/gtfs_validator.py): `gtfs_tools/gtfs_validator.py`

### External services

- [LLM client](https://github.com/sandesh339/gtfs_idea/blob/main/gtfs_tools/llm.py): `gtfs_tools/llm.py`
- [Official validator](https://github.com/sandesh339/gtfs_idea/blob/main/validator-service/app.py): `validator-service/app.py`

### Other components

- **Transit editor**

## Connections

- Transit editor → Chat and views: edits feed (evidence: `README.md`)
- Chat and views → API client: calls API (evidence: `frontend/src/App.jsx`)
- Chat and views → Chat panel: renders (evidence: `frontend/src/App.jsx`)
- Chat and views → Map, tables, diff: renders (evidence: `frontend/src/App.jsx`)
- Chat and views → Validation view: renders (evidence: `frontend/src/App.jsx`)
- Chat and views → Browser code runner: runs code (evidence: `frontend/src/App.jsx`)
- API client → FastAPI routes: sends requests
- FastAPI routes → Request authorization: protects routes (evidence: `server/app.py`)
- FastAPI routes → Session lifecycle: loads sessions (evidence: `server/app.py`)
- FastAPI routes → Session storage: configures backend (evidence: `server/app.py`)
- Session lifecycle → Session storage: persists state (evidence: `server/sessions.py`)
- Session lifecycle → Chat orchestration: reconstructs chat (evidence: `server/sessions.py`)
- FastAPI routes → Chat orchestration: handles requests (evidence: `server/app.py`)
- FastAPI routes → GTFS validation: validates feeds
- Chat and views → FastAPI routes: commits feed
- Chat orchestration → Request router: routes request (evidence: `gtfs_tools/chat.py`)
- Chat orchestration → Read-only lookup: dispatches lookup (evidence: `gtfs_tools/chat.py`)
- Chat orchestration → Function-call executor: dispatches edits (evidence: `gtfs_tools/chat.py`)
- Chat orchestration → Code generation: dispatches generation (evidence: `gtfs_tools/chat.py`)
- Chat orchestration → Entity-level diff: computes changes (evidence: `gtfs_tools/chat.py`)
- Request router → LLM client: requests decision (evidence: `gtfs_tools/router.py`)
- Read-only lookup → GTFS tools: dispatches read tools (evidence: `gtfs_tools/query.py`)
- Read-only lookup → LLM client: runs lookup loop (evidence: `gtfs_tools/query.py`)
- Function-call executor → GTFS tools: dispatches tools (evidence: `gtfs_tools/executor.py`)
- Function-call executor → LLM client: requests tool calls (evidence: `gtfs_tools/executor.py`)
- Code generation → LLM client: generates program (evidence: `gtfs_tools/codegen.py`)
- Function-call executor → GTFS feed model: edits feed (evidence: `gtfs_tools/executor.py`)
- GTFS tools → GTFS feed model: reads and edits (evidence: `gtfs_tools/tools.py`)
- Code generation → GTFS feed model: edits feed (evidence: `gtfs_tools/codegen.py`)
- Chat and views → Browser code runner: executes generated code (evidence: `frontend/src/App.jsx`)
- Scenario runner → Benchmark scenarios: loads scenarios (evidence: `gtfs_tools/scenarios.py`)
- FC vs codegen benchmark → Benchmark scenarios: loads cases (evidence: `run_benchmark.py`)
- FC vs codegen benchmark → Function-call executor: runs FC edits (evidence: `run_benchmark.py`)
- FC vs codegen benchmark → Code generation: runs generated edits (evidence: `run_benchmark.py`)
- FC vs codegen benchmark → Expected outcomes: uses answer keys (evidence: `run_benchmark.py`)
- FC vs codegen benchmark → Entity-level diff: measures changes (evidence: `run_benchmark.py`)
- Scenario runner → Outcome grading: grades scenarios (evidence: `gtfs_tools/scenarios.py`)
- Outcome grading → Entity-level diff: measures damage (evidence: `gtfs_tools/grader.py`)
- Outcome grading → GTFS validation: checks validity (evidence: `gtfs_tools/grader.py`)
- Outcome grading → Expected outcomes: checks correctness
- Outcome grading → Official validator: optional validation (evidence: `README.md`)
