# rohitdvv/fleetmind-agentic-trip-assignment architecture

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

- Interactive diagram: https://gitdiagram.com/rohitdvv/fleetmind-agentic-trip-assignment
- Repository: https://github.com/rohitdvv/fleetmind-agentic-trip-assignment

## Overview

FleetMind is a dispatch application that assigns trips to eligible drivers and exposes the decision and reasoning to a manager. The main workflow runs from the Streamlit UI through FastAPI, driver filtering, agent/tool evaluation, and persisted assignment back to the UI. Separate capabilities support counterfactual runs, manager overrides, natural-language queries, and scenario evaluations. The README documents these capabilities; some routes and UI sections were not sampled, so their internal wiring is shown only where documented.

Main entry points: [`backend.py`](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/backend.py) (FastAPI routes), [`agent.py`](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/agent.py) (Agent loop), [`frontend.py`](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/frontend.py) (Streamlit interface), [`db.py`](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/db.py) (SQLite queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dispatcher UI"]
  node_frontend["Streamlit interface<br/>[frontend.py]"]
  node_fleet_views["Fleet views<br/>[frontend.py]"]
  node_trace_cf["Trace and what-ifs<br/>[frontend.py]"]
end

subgraph group_api["API and workflows"]
  node_backend["FastAPI routes<br/>[backend.py]"]
  node_trip_flow["Trip assignment flow<br/>[backend.py]"]
  node_override["Override and audit<br/>[backend.py]"]
  node_nl_query["Natural-language query<br/>[backend.py]"]
  node_evals["Scenario evaluations<br/>[evals.py]"]
end

subgraph group_decision["Assignment decision"]
  node_agent["Agent loop<br/>[agent.py]"]
  node_rules["Eligibility filter<br/>[agent.py]"]
  node_tool_dispatch["Tool dispatch<br/>[tools.py]"]
end

subgraph group_data["Fleet data"]
  node_db_helpers["SQLite queries<br/>[db.py]"]
  node_database[("FleetMind database<br/>[fleetmind.db]")]
end

subgraph group_integrations["External services"]
  node_voice["Speech recognition"]
  node_geocoder["Address geocoder<br/>[frontend.py]"]
  node_llm_client["LLM client<br/>[llm.py]"]
end

node_manager(("Dispatcher"))
node_nominatim["Nominatim"]
node_llm_service["OpenAI service"]

node_manager -->|"uses"| node_frontend
node_frontend -->|"HTTP requests"| node_backend
node_frontend -.->|"transcribes speech"| node_voice
node_frontend -->|"geocodes addresses"| node_geocoder
node_geocoder -.->|"looks up locations"| node_nominatim
node_frontend -->|"renders fleet data"| node_fleet_views
node_frontend -->|"renders decisions"| node_trace_cf
node_backend -->|"handles trip requests"| node_trip_flow
node_trip_flow -->|"stores trip and assignment"| node_db_helpers
node_trip_flow -->|"runs assignment"| node_agent
node_agent -->|"loads trip and drivers"| node_db_helpers
node_agent -->|"filters candidates"| node_rules
node_agent -->|"dispatches tool calls"| node_tool_dispatch
node_tool_dispatch -->|"reads fleet records"| node_db_helpers
node_agent -->|"requests completions"| node_llm_client
node_llm_client -.->|"sends prompts"| node_llm_service
node_backend -->|"handles overrides"| node_override
node_override -->|"records audit and changes"| node_db_helpers
node_backend -->|"runs counterfactual"| node_agent
node_backend -->|"handles questions"| node_nl_query
node_nl_query -->|"generates SQL"| node_llm_client
node_nl_query -->|"executes SELECT"| node_db_helpers
node_backend -->|"runs scenarios"| node_evals
node_db_helpers -->|"reads and writes"| node_database
node_evals -->|"tests fallback scoring"| node_agent
node_fleet_views -->|"requests fleet data"| node_backend
node_trace_cf -->|"requests what-if runs"| node_backend

click node_frontend "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/frontend.py"
click node_fleet_views "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/frontend.py"
click node_trace_cf "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/frontend.py"
click node_geocoder "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/frontend.py"
click node_backend "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/backend.py"
click node_trip_flow "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/backend.py"
click node_override "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/backend.py"
click node_nl_query "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/backend.py"
click node_evals "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/evals.py"
click node_agent "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/agent.py"
click node_rules "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/agent.py"
click node_tool_dispatch "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/tools.py"
click node_llm_client "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/llm.py"
click node_db_helpers "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/db.py"
click node_database "https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/fleetmind.db"

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_frontend,node_fleet_views,node_trace_cf toneBlue
class node_backend,node_trip_flow,node_override,node_nl_query,node_evals toneAmber
class node_agent,node_rules,node_tool_dispatch toneMint
class node_db_helpers,node_database toneRose
class node_voice,node_geocoder,node_llm_client,node_manager,node_nominatim,node_llm_service toneIndigo
```

## Components

### Dispatcher UI

- [Streamlit interface](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/frontend.py): `frontend.py`
- [Fleet views](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/frontend.py): `frontend.py`
- [Trace and what-ifs](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/frontend.py): `frontend.py`

### API and workflows

- [FastAPI routes](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/backend.py): `backend.py`
- [Trip assignment flow](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/backend.py): `backend.py`
- [Override and audit](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/backend.py): `backend.py`
- [Natural-language query](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/backend.py): `backend.py`
- [Scenario evaluations](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/evals.py): `evals.py`

### Assignment decision

- [Agent loop](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/agent.py): `agent.py`
- [Eligibility filter](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/agent.py): `agent.py`
- [Tool dispatch](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/tools.py): `tools.py`

### Fleet data

- [SQLite queries](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/db.py): `db.py`
- [FleetMind database](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/fleetmind.db): `fleetmind.db`

### External services

- **Speech recognition**
- [Address geocoder](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/frontend.py): `frontend.py`
- [LLM client](https://github.com/rohitdvv/fleetmind-agentic-trip-assignment/blob/main/llm.py): `llm.py`

### Other components

- **Dispatcher**
- **Nominatim**
- **OpenAI service**

## Connections

- Dispatcher → Streamlit interface: uses
- Streamlit interface → FastAPI routes: HTTP requests
- Streamlit interface → Speech recognition: transcribes speech
- Streamlit interface → Address geocoder: geocodes addresses
- Address geocoder → Nominatim: looks up locations
- Streamlit interface → Fleet views: renders fleet data
- Streamlit interface → Trace and what-ifs: renders decisions
- FastAPI routes → Trip assignment flow: handles trip requests
- Trip assignment flow → SQLite queries: stores trip and assignment
- Trip assignment flow → Agent loop: runs assignment
- Agent loop → SQLite queries: loads trip and drivers
- Agent loop → Eligibility filter: filters candidates
- Agent loop → Tool dispatch: dispatches tool calls
- Tool dispatch → SQLite queries: reads fleet records
- Agent loop → LLM client: requests completions
- LLM client → OpenAI service: sends prompts
- FastAPI routes → Override and audit: handles overrides
- Override and audit → SQLite queries: records audit and changes
- FastAPI routes → Agent loop: runs counterfactual
- FastAPI routes → Natural-language query: handles questions
- Natural-language query → LLM client: generates SQL
- Natural-language query → SQLite queries: executes SELECT
- FastAPI routes → Scenario evaluations: runs scenarios
- SQLite queries → FleetMind database: reads and writes
- Scenario evaluations → Agent loop: tests fallback scoring
- Fleet views → FastAPI routes: requests fleet data
- Trace and what-ifs → FastAPI routes: requests what-if runs