# psyc-syntax/apsrtc-transit-planner architecture

> Architecture diagram of the GitHub repository psyc-syntax/apsrtc-transit-planner, 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/psyc-syntax/apsrtc-transit-planner
- Repository: https://github.com/psyc-syntax/apsrtc-transit-planner

## Overview

Markbus is a Flutter transit-planning app for APSRTC journeys. The documented user flow is choosing origin, destination and travel time, then viewing time-aware route options and checkpoint transfers; the app also has stop search, scheduled-trip planning, saved trips and data/settings screens. The tree supports these product areas, but most Dart sources were not sampled, so internal call wiring is shown only where the README or file responsibilities make it clear. The README describes C++/FFI, Firebase and railway support as in-progress or roadmap capabilities, not established integrations.

Main entry points: [`lib/screens/home_screen.dart`](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/home_screen.dart) (Route search), [`lib/helpers/database_helper.dart`](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/helpers/database_helper.dart) (Database access), [`lib/main.dart`](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/main.dart) (App entry), [`lib/screens/route_results_screen.dart`](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/route_results_screen.dart) (Route results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_app["App entry<br/>[main.dart]"]
  node_home["Route search<br/>[home_screen.dart]"]
  node_stopsearch["Stop search"]
  node_results["Route results"]
  node_navigation["Trip navigation"]
  node_options["Settings and support"]
end

subgraph group_routing["Route planning"]
  node_routealgo["Route algorithm"]
  node_nativeengine["C++ routing engine<br/>[marksAlgorithm.cpp]"]
end

subgraph group_journeys["Schedules and trips"]
  node_schedule["Schedule search"]
  node_schedulealgo["Schedule algorithm"]
  node_scheduled["Scheduled trips"]
  node_saved["Saved trips<br/>[trips_screen.dart]"]
  node_savelogic["Trip persistence logic<br/>[save_trips.dart]"]
end

subgraph group_data["Local data"]
  node_provider["App data state"]
  node_dbhelper["Database access"]
  node_database[("Local SQLite data<br/>[ap_v2.db]")]
  node_binhelper["Engine data loader"]
  node_bindata["Routing binary data<br/>[B_arr.bin]"]
  node_updates["Data update screen"]
end

node_commuter(("Commuter"))

node_commuter -->|"opens"| node_app
node_app -->|"shows"| node_home
node_home -->|"searches stops"| node_stopsearch
node_home -->|"requests routes"| node_routealgo
node_routealgo -->|"returns options"| node_results
node_results -->|"starts trip"| node_navigation
node_commuter -->|"requests schedule"| node_schedule
node_schedule -->|"requests trips"| node_schedulealgo
node_schedulealgo -->|"returns trips"| node_scheduled
node_commuter -->|"views saved trips"| node_saved
node_saved -->|"loads trips"| node_savelogic
node_savelogic -->|"persists trips"| node_dbhelper
node_dbhelper -->|"reads and writes"| node_database
node_home -->|"uses app state"| node_provider
node_updates -->|"manages local data"| node_dbhelper
node_binhelper -->|"loads files"| node_bindata

click node_app "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/main.dart"
click node_home "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/home_screen.dart"
click node_stopsearch "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/stop_search_screen.dart"
click node_results "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/route_results_screen.dart"
click node_navigation "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/trip_navigation_screen.dart"
click node_options "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/more_options_screen.dart"
click node_provider "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/providers/app_data_provider.dart"
click node_routealgo "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/logic/marks_algorithm.dart"
click node_nativeengine "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/native/marksAlgorithm.cpp"
click node_schedule "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/schedule_screen.dart"
click node_schedulealgo "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/logic/marks_schedule_trips_algorithm.dart"
click node_scheduled "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/scheduled_trips_screen.dart"
click node_saved "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/trips_screen.dart"
click node_savelogic "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/logic/save_trips.dart"
click node_dbhelper "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/helpers/database_helper.dart"
click node_database "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/assets/data/ap_v2.db"
click node_binhelper "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/helpers/bin_files_helper.dart"
click node_bindata "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/assets/bin%20files/B_arr.bin"
click node_updates "https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/settings/update_data_screen.dart"

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_app,node_home,node_stopsearch,node_results,node_navigation,node_options toneBlue
class node_routealgo,node_nativeengine toneAmber
class node_schedule,node_schedulealgo,node_scheduled,node_saved,node_savelogic toneMint
class node_provider,node_dbhelper,node_database,node_binhelper,node_bindata,node_updates toneRose
class node_commuter toneIndigo
```

## Components

### App experience

- [App entry](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/main.dart): `lib/main.dart`
- [Route search](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/home_screen.dart): `lib/screens/home_screen.dart`
- [Stop search](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/stop_search_screen.dart): `lib/screens/stop_search_screen.dart`
- [Route results](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/route_results_screen.dart): `lib/screens/route_results_screen.dart`
- [Trip navigation](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/trip_navigation_screen.dart): `lib/screens/trip_navigation_screen.dart`
- [Settings and support](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/more_options_screen.dart): `lib/screens/more_options_screen.dart`

### Route planning

- [Route algorithm](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/logic/marks_algorithm.dart): `lib/logic/marks_algorithm.dart`
- [C++ routing engine](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/native/marksAlgorithm.cpp): `lib/native/marksAlgorithm.cpp`

### Schedules and trips

- [Schedule search](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/schedule_screen.dart): `lib/screens/schedule_screen.dart`
- [Schedule algorithm](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/logic/marks_schedule_trips_algorithm.dart): `lib/logic/marks_schedule_trips_algorithm.dart`
- [Scheduled trips](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/scheduled_trips_screen.dart): `lib/screens/scheduled_trips_screen.dart`
- [Saved trips](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/trips_screen.dart): `lib/screens/trips_screen.dart`
- [Trip persistence logic](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/logic/save_trips.dart): `lib/logic/save_trips.dart`

### Local data

- [App data state](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/providers/app_data_provider.dart): `lib/providers/app_data_provider.dart`
- [Database access](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/helpers/database_helper.dart): `lib/helpers/database_helper.dart`
- [Local SQLite data](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/assets/data/ap_v2.db): `assets/data/ap_v2.db`
- [Engine data loader](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/helpers/bin_files_helper.dart): `lib/helpers/bin_files_helper.dart`
- [Routing binary data](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/assets/bin%20files/B_arr.bin): `assets/bin files/B_arr.bin`
- [Data update screen](https://github.com/psyc-syntax/apsrtc-transit-planner/blob/main/lib/screens/settings/update_data_screen.dart): `lib/screens/settings/update_data_screen.dart`

### Other components

- **Commuter**

## Connections

- Commuter → App entry: opens
- App entry → Route search: shows
- Route search → Stop search: searches stops
- Route search → Route algorithm: requests routes
- Route algorithm → Route results: returns options
- Route results → Trip navigation: starts trip
- Commuter → Schedule search: requests schedule
- Schedule search → Schedule algorithm: requests trips
- Schedule algorithm → Scheduled trips: returns trips
- Commuter → Saved trips: views saved trips
- Saved trips → Trip persistence logic: loads trips
- Trip persistence logic → Database access: persists trips
- Database access → Local SQLite data: reads and writes
- Route search → App data state: uses app state
- Data update screen → Database access: manages local data
- Engine data loader → Routing binary data: loads files