# imondol41/bus-tracking architecture

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

## Overview

University Bus Tracker is a Flutter app for students tracking buses and for administrators managing users and the fleet. The principal workflow is role-based sign-in, viewing buses and their locations, and opening a tracked bus on a map with distance and ETA information. Admins manage bus records; super admins review admin requests and oversee users. The README documents Supabase authentication/realtime and mapping capabilities, but the sampled source does not show call sites, so links among UI, providers, services, and external systems are intentionally limited.

Main entry points: [`lib/providers/auth_provider.dart`](https://github.com/imondol41/bus-tracking/blob/main/lib/providers/auth_provider.dart) (Auth state), [`lib/screens/student/map_tracker_screen.dart`](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/student/map_tracker_screen.dart) (Map tracking), [`lib/screens/auth/signup_screen.dart`](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/auth/signup_screen.dart) (Sign up), [`lib/screens/admin/admin_panel_screen.dart`](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/admin/admin_panel_screen.dart) (Fleet management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry"]
  node_main["App entry<br/>[main.dart]"]
  node_router["Navigation<br/>[app_router.dart]"]
  node_theme["Theme state"]
end

subgraph group_identity["Identity and roles"]
  node_authcheck["Auth routing"]
  node_login["Sign in<br/>[login_screen.dart]"]
  node_signup["Sign up<br/>[signup_screen.dart]"]
  node_otp["Email verification"]
  node_authprovider["Auth state<br/>[auth_provider.dart]"]
  node_profile["User profile"]
  node_user_model["User model<br/>[user_model.dart]"]
end

subgraph group_tracking["Bus tracking"]
  node_dashboard["Bus dashboard"]
  node_tracker["Map tracking"]
  node_busprovider["Bus tracking state"]
  node_busmodel["Bus model<br/>[bus_model.dart]"]
  node_location["GPS location"]
  node_distance["Distance and ETA"]
  node_pluscode["Plus Codes"]
  node_maps["Map integration"]
  node_distancewidget["Distance display"]
end

subgraph group_operations["Administration"]
  node_admin["Fleet management"]
  node_busform["Bus editor"]
  node_superadmin["Admin oversight"]
end

node_user(("App user"))
node_supabase[("Supabase")]
node_mapservice["Mapping platform"]

node_user -->|"opens"| node_main
node_main -->|"starts navigation"| node_router
node_user -->|"enters app"| node_authcheck
node_authcheck -->|"routes unauthenticated"| node_login
node_user -->|"signs in"| node_login
node_user -->|"registers"| node_signup
node_signup -->|"verifies email"| node_otp
node_login -->|"uses auth state"| node_authprovider
node_signup -->|"uses auth state"| node_authprovider
node_otp -->|"uses auth state"| node_authprovider
node_authprovider -->|"authenticates"| node_supabase
node_user -->|"browses buses"| node_dashboard
node_dashboard -->|"shows tracking state"| node_busprovider
node_busprovider -->|"syncs bus data"| node_supabase
node_user -->|"tracks bus"| node_tracker
node_tracker -->|"renders map"| node_maps
node_maps -.->|"displays map"| node_mapservice
node_tracker -->|"uses GPS"| node_location
node_tracker -->|"calculates distance"| node_distance
node_distance -->|"provides metrics"| node_distancewidget
node_tracker -->|"uses location codes"| node_pluscode
node_user -->|"edits profile"| node_profile
node_profile -->|"uses account state"| node_authprovider
node_user -->|"manages fleet"| node_admin
node_admin -->|"edits buses"| node_busform
node_admin -->|"manages bus state"| node_busprovider
node_user -->|"reviews requests"| node_superadmin
node_superadmin -->|"manages roles"| node_authprovider

click node_main "https://github.com/imondol41/bus-tracking/blob/main/lib/main.dart"
click node_router "https://github.com/imondol41/bus-tracking/blob/main/lib/config/app_router.dart"
click node_theme "https://github.com/imondol41/bus-tracking/blob/main/lib/providers/theme_provider.dart"
click node_authcheck "https://github.com/imondol41/bus-tracking/blob/main/lib/screens/auth/auth_checker_screen.dart"
click node_login "https://github.com/imondol41/bus-tracking/blob/main/lib/screens/auth/login_screen.dart"
click node_signup "https://github.com/imondol41/bus-tracking/blob/main/lib/screens/auth/signup_screen.dart"
click node_otp "https://github.com/imondol41/bus-tracking/blob/main/lib/screens/auth/otp_verification_screen.dart"
click node_authprovider "https://github.com/imondol41/bus-tracking/blob/main/lib/providers/auth_provider.dart"
click node_profile "https://github.com/imondol41/bus-tracking/blob/main/lib/screens/student/profile_screen.dart"
click node_user_model "https://github.com/imondol41/bus-tracking/blob/main/lib/models/user_model.dart"
click node_dashboard "https://github.com/imondol41/bus-tracking/blob/main/lib/screens/student/dashboard_screen.dart"
click node_tracker "https://github.com/imondol41/bus-tracking/blob/main/lib/screens/student/map_tracker_screen.dart"
click node_busprovider "https://github.com/imondol41/bus-tracking/blob/main/lib/providers/bus_tracker_provider.dart"
click node_busmodel "https://github.com/imondol41/bus-tracking/blob/main/lib/models/bus_model.dart"
click node_location "https://github.com/imondol41/bus-tracking/blob/main/lib/services/location_service.dart"
click node_distance "https://github.com/imondol41/bus-tracking/blob/main/lib/services/distance_service.dart"
click node_pluscode "https://github.com/imondol41/bus-tracking/blob/main/lib/services/plus_code_service.dart"
click node_maps "https://github.com/imondol41/bus-tracking/blob/main/lib/services/openlayers_map_service.dart"
click node_distancewidget "https://github.com/imondol41/bus-tracking/blob/main/lib/widgets/distance_info_widget.dart"
click node_admin "https://github.com/imondol41/bus-tracking/blob/main/lib/screens/admin/admin_panel_screen.dart"
click node_busform "https://github.com/imondol41/bus-tracking/blob/main/lib/screens/admin/bus_form_screen.dart"
click node_superadmin "https://github.com/imondol41/bus-tracking/blob/main/lib/screens/super_admin/super_admin_panel_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_main,node_router,node_theme,node_user toneBlue
class node_authcheck,node_login,node_signup,node_otp,node_authprovider,node_profile,node_user_model,node_supabase toneAmber
class node_dashboard,node_tracker,node_busprovider,node_busmodel,node_location,node_distance,node_pluscode,node_maps,node_distancewidget toneMint
class node_admin,node_busform,node_superadmin toneRose
class node_mapservice toneIndigo
```

## Components

### App entry

- [App entry](https://github.com/imondol41/bus-tracking/blob/main/lib/main.dart): `lib/main.dart`
- [Navigation](https://github.com/imondol41/bus-tracking/blob/main/lib/config/app_router.dart): `lib/config/app_router.dart`
- [Theme state](https://github.com/imondol41/bus-tracking/blob/main/lib/providers/theme_provider.dart): `lib/providers/theme_provider.dart`

### Identity and roles

- [Auth routing](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/auth/auth_checker_screen.dart): `lib/screens/auth/auth_checker_screen.dart`
- [Sign in](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/auth/login_screen.dart): `lib/screens/auth/login_screen.dart`
- [Sign up](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/auth/signup_screen.dart): `lib/screens/auth/signup_screen.dart`
- [Email verification](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/auth/otp_verification_screen.dart): `lib/screens/auth/otp_verification_screen.dart`
- [Auth state](https://github.com/imondol41/bus-tracking/blob/main/lib/providers/auth_provider.dart): `lib/providers/auth_provider.dart`
- [User profile](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/student/profile_screen.dart): `lib/screens/student/profile_screen.dart`
- [User model](https://github.com/imondol41/bus-tracking/blob/main/lib/models/user_model.dart): `lib/models/user_model.dart`

### Bus tracking

- [Bus dashboard](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/student/dashboard_screen.dart): `lib/screens/student/dashboard_screen.dart`
- [Map tracking](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/student/map_tracker_screen.dart): `lib/screens/student/map_tracker_screen.dart`
- [Bus tracking state](https://github.com/imondol41/bus-tracking/blob/main/lib/providers/bus_tracker_provider.dart): `lib/providers/bus_tracker_provider.dart`
- [Bus model](https://github.com/imondol41/bus-tracking/blob/main/lib/models/bus_model.dart): `lib/models/bus_model.dart`
- [GPS location](https://github.com/imondol41/bus-tracking/blob/main/lib/services/location_service.dart): `lib/services/location_service.dart`
- [Distance and ETA](https://github.com/imondol41/bus-tracking/blob/main/lib/services/distance_service.dart): `lib/services/distance_service.dart`
- [Plus Codes](https://github.com/imondol41/bus-tracking/blob/main/lib/services/plus_code_service.dart): `lib/services/plus_code_service.dart`
- [Map integration](https://github.com/imondol41/bus-tracking/blob/main/lib/services/openlayers_map_service.dart): `lib/services/openlayers_map_service.dart`
- [Distance display](https://github.com/imondol41/bus-tracking/blob/main/lib/widgets/distance_info_widget.dart): `lib/widgets/distance_info_widget.dart`

### Administration

- [Fleet management](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/admin/admin_panel_screen.dart): `lib/screens/admin/admin_panel_screen.dart`
- [Bus editor](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/admin/bus_form_screen.dart): `lib/screens/admin/bus_form_screen.dart`
- [Admin oversight](https://github.com/imondol41/bus-tracking/blob/main/lib/screens/super_admin/super_admin_panel_screen.dart): `lib/screens/super_admin/super_admin_panel_screen.dart`

### Other components

- **App user**
- **Supabase**
- **Mapping platform**

## Connections

- App user → App entry: opens
- App entry → Navigation: starts navigation
- App user → Auth routing: enters app
- Auth routing → Sign in: routes unauthenticated
- App user → Sign in: signs in
- App user → Sign up: registers
- Sign up → Email verification: verifies email
- Sign in → Auth state: uses auth state
- Sign up → Auth state: uses auth state
- Email verification → Auth state: uses auth state
- Auth state → Supabase: authenticates
- App user → Bus dashboard: browses buses
- Bus dashboard → Bus tracking state: shows tracking state
- Bus tracking state → Supabase: syncs bus data
- App user → Map tracking: tracks bus
- Map tracking → Map integration: renders map
- Map integration → Mapping platform: displays map
- Map tracking → GPS location: uses GPS
- Map tracking → Distance and ETA: calculates distance
- Distance and ETA → Distance display: provides metrics
- Map tracking → Plus Codes: uses location codes
- App user → User profile: edits profile
- User profile → Auth state: uses account state
- App user → Fleet management: manages fleet
- Fleet management → Bus editor: edits buses
- Fleet management → Bus tracking state: manages bus state
- App user → Admin oversight: reviews requests
- Admin oversight → Auth state: manages roles