# aldhaf2007/voicebased-transport-system architecture

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

- Interactive diagram: https://gitdiagram.com/aldhaf2007/voicebased-transport-system
- Repository: https://github.com/aldhaf2007/voicebased-transport-system

## Overview

Voice Transport System is a Flask transport-search and booking application. A traveler submits typed or recorded speech; the server transcribes audio when needed, extracts and normalizes stations, searches the route graph, looks up schedules, and returns results for display or spoken summary. Users can authenticate, book or cancel trips, and review booking history; administrators manage stations, routes, and schedules. The sampled source shows the Flask/database boundary and browser behavior; some route wiring and database operations are described by the README rather than fully sampled.

Main entry points: [`app.py`](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/app.py) (Flask request handlers), [`static/js/main.js`](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/static/js/main.js) (Search and booking UI), [`database.py`](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/database.py) (Booking and cancellation), [`templates/admin.html`](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/templates/admin.html) (Admin dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser experience"]
  node_browser["Search and booking UI<br/>[main.js]"]
  node_pages["Rendered pages"]
  node_service_worker["Asset cache<br/>[service-worker.js]"]
end

subgraph group_search["Route search"]
  node_flask["Flask request handlers<br/>[app.py]"]
  node_station_parse["Station extraction<br/>[app.py]"]
  node_speech_input["Whisper transcription<br/>[app.py]"]
  node_speech_output["Kokoro synthesis<br/>[app.py]"]
  node_data_bridge["Transport data access<br/>[database.py]"]
  node_route_graph[("Station and route graph")]
  node_schedule_store[("Schedules and transport types")]
end

subgraph group_booking["Accounts and bookings"]
  node_identity["User authentication<br/>[database.py]"]
  node_booking_flow["Booking and cancellation<br/>[database.py]"]
  node_booking_store[("Users and bookings")]
  node_receipt["Local booking receipt<br/>[app.py]"]
end

subgraph group_admin["Network administration"]
  node_admin_ui["Admin dashboard<br/>[admin.html]"]
  node_admin_ops["Network and schedule CRUD<br/>[database.py]"]
end

node_traveler(("Traveler"))
node_speech_service["Whisper model"]
node_kokoro["Kokoro TTS"]

node_traveler -->|"enters request"| node_browser
node_browser -->|"sends search"| node_flask
node_browser -->|"uploads audio"| node_flask
node_flask -->|"transcribes audio"| node_speech_input
node_speech_input -->|"runs model"| node_speech_service
node_flask -->|"extracts stations"| node_station_parse
node_flask -->|"queries routes"| node_data_bridge
node_data_bridge -->|"finds paths"| node_route_graph
node_data_bridge -->|"reads schedules"| node_schedule_store
node_flask -->|"returns results"| node_browser
node_browser -->|"requests summary"| node_speech_output
node_speech_output -->|"synthesizes speech"| node_kokoro
node_flask -->|"renders pages"| node_pages
node_browser -->|"authenticates"| node_flask
node_flask -->|"checks credentials"| node_identity
node_identity -->|"reads and writes users"| node_booking_store
node_browser -->|"submits booking"| node_flask
node_flask -->|"creates booking"| node_booking_flow
node_booking_flow -->|"locks and updates seats"| node_schedule_store
node_booking_flow -->|"writes booking"| node_booking_store
node_flask -->|"saves receipt"| node_receipt
node_browser -->|"requests history or cancellation"| node_flask
node_flask -->|"loads or cancels booking"| node_booking_flow
node_traveler -->|"manages network"| node_admin_ui
node_admin_ui -->|"submits admin actions"| node_flask
node_flask -->|"dispatches CRUD"| node_admin_ops
node_admin_ops -->|"updates stations and routes"| node_route_graph
node_admin_ops -->|"updates schedules"| node_schedule_store
node_browser -.->|"uses cached assets"| node_service_worker

click node_browser "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/static/js/main.js"
click node_pages "https://github.com/aldhaf2007/voicebased-transport-system/tree/main/templates"
click node_service_worker "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/static/service-worker.js"
click node_flask "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/app.py"
click node_station_parse "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/app.py"
click node_speech_input "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/app.py"
click node_speech_output "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/app.py"
click node_data_bridge "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/database.py"
click node_identity "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/database.py"
click node_booking_flow "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/database.py"
click node_admin_ui "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/templates/admin.html"
click node_admin_ops "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/database.py"
click node_receipt "https://github.com/aldhaf2007/voicebased-transport-system/blob/main/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_browser,node_pages,node_service_worker toneBlue
class node_flask,node_station_parse,node_speech_input,node_speech_output,node_data_bridge,node_route_graph,node_schedule_store toneAmber
class node_identity,node_booking_flow,node_booking_store,node_receipt toneMint
class node_admin_ui,node_admin_ops toneRose
class node_traveler,node_speech_service,node_kokoro toneIndigo
```

## Components

### Browser experience

- [Search and booking UI](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/static/js/main.js): `static/js/main.js`
- [Rendered pages](https://github.com/aldhaf2007/voicebased-transport-system/tree/main/templates): `templates`
- [Asset cache](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/static/service-worker.js): `static/service-worker.js`

### Route search

- [Flask request handlers](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/app.py): `app.py`
- [Station extraction](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/app.py): `app.py`
- [Whisper transcription](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/app.py): `app.py`
- [Kokoro synthesis](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/app.py): `app.py`
- [Transport data access](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/database.py): `database.py`
- **Station and route graph**
- **Schedules and transport types**

### Accounts and bookings

- [User authentication](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/database.py): `database.py`
- [Booking and cancellation](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/database.py): `database.py`
- **Users and bookings**
- [Local booking receipt](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/app.py): `app.py`

### Network administration

- [Admin dashboard](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/templates/admin.html): `templates/admin.html`
- [Network and schedule CRUD](https://github.com/aldhaf2007/voicebased-transport-system/blob/main/database.py): `database.py`

### Other components

- **Traveler**
- **Whisper model**
- **Kokoro TTS**

## Connections

- Traveler → Search and booking UI: enters request
- Search and booking UI → Flask request handlers: sends search
- Search and booking UI → Flask request handlers: uploads audio
- Flask request handlers → Whisper transcription: transcribes audio
- Whisper transcription → Whisper model: runs model
- Flask request handlers → Station extraction: extracts stations
- Flask request handlers → Transport data access: queries routes
- Transport data access → Station and route graph: finds paths
- Transport data access → Schedules and transport types: reads schedules
- Flask request handlers → Search and booking UI: returns results
- Search and booking UI → Kokoro synthesis: requests summary
- Kokoro synthesis → Kokoro TTS: synthesizes speech
- Flask request handlers → Rendered pages: renders pages
- Search and booking UI → Flask request handlers: authenticates
- Flask request handlers → User authentication: checks credentials
- User authentication → Users and bookings: reads and writes users
- Search and booking UI → Flask request handlers: submits booking
- Flask request handlers → Booking and cancellation: creates booking
- Booking and cancellation → Schedules and transport types: locks and updates seats
- Booking and cancellation → Users and bookings: writes booking
- Flask request handlers → Local booking receipt: saves receipt
- Search and booking UI → Flask request handlers: requests history or cancellation
- Flask request handlers → Booking and cancellation: loads or cancels booking
- Traveler → Admin dashboard: manages network
- Admin dashboard → Flask request handlers: submits admin actions
- Flask request handlers → Network and schedule CRUD: dispatches CRUD
- Network and schedule CRUD → Station and route graph: updates stations and routes
- Network and schedule CRUD → Schedules and transport types: updates schedules
- Search and booking UI → Asset cache: uses cached assets