# samiul-hossen-sarkar-santo/bus_tracker_user_app architecture

> Architecture diagram of the GitHub repository samiul-hossen-sarkar-santo/bus_tracker_user_app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samiul-hossen-sarkar-santo/bus_tracker_user_app
- Repository: https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app

## Overview

1. **Project shape**
   - This is a **Flutter** client application called **Bus Tracker User App**.
   - It is built once in Dart and deployed through the standard Flutter platform shells for **Android, iOS, web, Windows, macOS, and Linux**.

2. **Entry and app bootstrap**
   - The primary app code lives in `lib/main.dart`.
   - `lib/main_screen.dart` likely serves as the top-level app shell or navigation host, with the rest of the UI organized into feature screens.
   - `lib/firebase_options.dart` and the platform Firebase config files indicate Firebase is wired into startup, even though no backend feature code is visible in the tree.

3. **UI composition**
   - The app is screen-driven, with major views under `lib/screens/`:
     - `home.dart` for the main route grid and search entry point
     - `search_page.dart` for search-focused browsing
     - `routes_list_page.dart` and `all_routes.dart` for route listings / route detail navigation
     - `map_page.dart` and `emergency_page.dart` as additional functional screens
     - `loading.dart` for splash/initial loading behavior
   - The README’s “route details with zoomable images” feature suggests one of the route screens also acts as the detail view.

4. **Core data model**
   - Application data is organized locally in `lib/models/`:
     - `route_model.dart` for route/stoppage structure
     - `bus_catalogue.dart` for the bus route catalog itself
   - The README describes real-time filtering over route titles and stoppage names, so the app appears to search against an in-memory/local catalogue rather than a remote API.

5. **Search and browsing flow**
   - The main user flow is:
     - open the home screen
     - type in the search bar
     - filter visible route cards dynamically
     - tap a card to open route details
   - Search is a **local UI-driven filter**, not a separate search service in the repository.

6. **Route detail experience**
   - Route detail views are image-centric, with zoomable route images and placeholder text when no image exists.
   - `assets/images/` is the likely source for route graphics, maps, or illustrative content used in these screens.

7. **State and theming**
   - `lib/providers/theme_provider.dart` provides app-wide theme state, likely for light/dark or brand styling.
   - `lib/theme/app_theme.dart` defines the actual visual system used throughout the screens.
   - This is the only obvious cross-screen state layer in the repo; most other logic is screen-local.

8. **Navigation boundary**
   - Navigation is internal to the Flutter app, with the main interaction pattern being **screen-to-screen routing** and back navigation.
   - The README explicitly mentions a themed back button on route pages, so the navigation layer is part of the UX design rather than a separate infrastructure layer.

9. **Firebase and deployment artifacts**
   - The repo contains Firebase-related configuration: `firebase.json`, `.firebaserc`, `database.rules.json`, and Android `google-services.json`.
   - That means the app is prepared for Firebase-backed services or hosting, but the visible Dart code does not show a heavy server/backend architecture.
   - For an architecture diagram, treat Firebase as a configured external boundary, not as a visible internal subsystem.

10. **Platform scaffolding**
   - `android/`, `ios/`, `web/`, `windows/`, `macos/`, and `linux/` are generated host layers that wrap the same Flutter app.
   - These directories mainly contain launcher, manifest, and build configuration rather than business logic.

11. **Testing and quality**
   - `test/widget_test.dart` shows there is at least basic Flutter widget testing.
   - `analysis_options.yaml` and `devtools_options.yaml` indicate standard Dart linting and developer tooling, but no large test or CI subsystem is present in the tree.

12. **Overall architecture**
   - The app is a **frontend-only Flutter catalog browser**: UI screens consume local model data, apply search/filtering, render themed route cards/details, and optionally sit on top of Firebase configuration for future or auxiliary services.
   - The clearest diagram boundaries are: **Flutter UI screens**, **local route/catalog models**, **theme/state provider**, **asset/image resources**, and **external Firebase/platform wrappers**.

Main entry points: [`lib/main.dart`](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/main.dart) (Main), [`lib/screens/home.dart`](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/home.dart) (Home), [`lib/main_screen.dart`](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/main_screen.dart) (App Shell), [`lib/screens/all_routes.dart`](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/all_routes.dart) (Route Detail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_core["App Core"]
  node_main["Main<br/>flutter entrypoint<br/>[main.dart]"]
  node_main_screen["App Shell<br/>navigation shell<br/>[main_screen.dart]"]
  node_theme_provider["Theme State<br/>app state"]
  node_app_theme["Theme System<br/>design system<br/>[app_theme.dart]"]
  node_bus_catalogue[("Bus Catalogue<br/>catalog data<br/>[bus_catalogue.dart]")]
  node_route_model[("Route Model<br/>data model<br/>[route_model.dart]")]
end

subgraph group_features["Screens"]
  node_loading["Loading<br/>splash screen<br/>[loading.dart]"]
  node_home["Home<br/>entry screen<br/>[home.dart]"]
  node_search_page["Search<br/>browse screen<br/>[search_page.dart]"]
  node_routes_list_page["Routes List<br/>listing screen"]
  node_all_routes["Route Detail<br/>detail screen<br/>[all_routes.dart]"]
  node_map_page["Map<br/>utility screen<br/>[map_page.dart]"]
  node_emergency_page["Emergency<br/>utility screen"]
end

subgraph group_platforms["Platform Shells"]
  node_android_shell["Android<br/>platform shell"]
  node_ios_shell["iOS<br/>platform shell"]
  node_web_shell["Web<br/>platform shell"]
  node_windows_shell["Windows<br/>platform shell"]
  node_macos_shell["macOS<br/>platform shell"]
  node_linux_shell["Linux<br/>platform shell"]
end

subgraph group_backend["External Config"]
  node_firebase_options["Firebase Options<br/>firebase config"]
  node_firebase_json["Firebase Hosting<br/>deployment config<br/>[firebase.json]"]
  node_firebase_rules["Database Rules<br/>firebase rules"]
  node_google_services["Google Services<br/>android firebase config"]
end

node_assets_images["Images<br/>asset bundle"]

node_main -->|"init"| node_firebase_options
node_main -->|"launches"| node_main_screen
node_main_screen -->|"shows"| node_loading
node_main_screen -->|"hosts"| node_home
node_home -->|"searches"| node_search_page
node_home -->|"navigates"| node_routes_list_page
node_routes_list_page -->|"details"| node_all_routes
node_search_page -->|"opens"| node_all_routes
node_all_routes -->|"renders"| node_assets_images
node_all_routes -->|"links"| node_map_page
node_home -->|"links"| node_map_page
node_home -->|"links"| node_emergency_page
node_home -->|"filters"| node_bus_catalogue
node_search_page -->|"filters"| node_bus_catalogue
node_routes_list_page -->|"uses"| node_route_model
node_all_routes -->|"uses"| node_route_model
node_theme_provider -->|"applies"| node_app_theme
node_main_screen -->|"consumes"| node_theme_provider
node_main_screen -->|"styles"| node_app_theme
node_android_shell -->|"hosts"| node_main
node_ios_shell -->|"hosts"| node_main
node_web_shell -->|"hosts"| node_main
node_windows_shell -->|"hosts"| node_main
node_macos_shell -->|"hosts"| node_main
node_linux_shell -->|"hosts"| node_main
node_firebase_json -.->|"pairs with"| node_firebase_options
node_firebase_rules -.->|"boundaries"| node_firebase_options
node_google_services -.->|"platform config"| node_firebase_options

click node_main "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/main.dart"
click node_main_screen "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/main_screen.dart"
click node_theme_provider "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/providers/theme_provider.dart"
click node_app_theme "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/theme/app_theme.dart"
click node_bus_catalogue "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/models/bus_catalogue.dart"
click node_route_model "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/models/route_model.dart"
click node_loading "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/loading.dart"
click node_home "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/home.dart"
click node_search_page "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/search_page.dart"
click node_routes_list_page "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/routes_list_page.dart"
click node_all_routes "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/all_routes.dart"
click node_map_page "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/map_page.dart"
click node_emergency_page "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/emergency_page.dart"
click node_assets_images "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/assets/images"
click node_firebase_options "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/firebase_options.dart"
click node_firebase_json "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/firebase.json"
click node_firebase_rules "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/database.rules.json"
click node_google_services "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/android/app/google-services.json"
click node_android_shell "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/android"
click node_ios_shell "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/ios"
click node_web_shell "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/web"
click node_windows_shell "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/windows"
click node_macos_shell "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/macos"
click node_linux_shell "https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/linux"

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_main_screen,node_theme_provider,node_app_theme,node_bus_catalogue,node_route_model toneBlue
class node_loading,node_home,node_search_page,node_routes_list_page,node_all_routes,node_map_page,node_emergency_page toneAmber
class node_android_shell,node_ios_shell,node_web_shell,node_windows_shell,node_macos_shell,node_linux_shell toneMint
class node_firebase_options,node_firebase_json,node_firebase_rules,node_google_services toneRose
class node_assets_images toneNeutral
```

## Components

### App Core

Flutter entrypoint, shell, theming, and shared data structures

- [Main](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/main.dart): flutter entrypoint · App startup and bootstrap · `lib/main.dart`
- [App Shell](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/main_screen.dart): navigation shell · Top-level app scaffold and route host · `lib/main_screen.dart`
- [Theme State](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/providers/theme_provider.dart): app state · Shared theme mode and styling state · `lib/providers/theme_provider.dart`
- [Theme System](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/theme/app_theme.dart): design system · Central visual theme definitions · `lib/theme/app_theme.dart`
- [Bus Catalogue](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/models/bus_catalogue.dart): catalog data · Local route and stoppage catalogue · `lib/models/bus_catalogue.dart`
- [Route Model](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/models/route_model.dart): data model · Route and stoppage structure · `lib/models/route_model.dart`

### Screens

Primary user-facing views and navigation targets

- [Loading](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/loading.dart): splash screen · Initial loading and startup screen · `lib/screens/loading.dart`
- [Home](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/home.dart): entry screen · Main route grid and search entry point · `lib/screens/home.dart`
- [Search](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/search_page.dart): browse screen · Search-focused browsing view · `lib/screens/search_page.dart`
- [Routes List](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/routes_list_page.dart): listing screen · Route listing and navigation view · `lib/screens/routes_list_page.dart`
- [Route Detail](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/all_routes.dart): detail screen · Route details and zoomable imagery · `lib/screens/all_routes.dart`
- [Map](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/map_page.dart): utility screen · Map-oriented route view · `lib/screens/map_page.dart`
- [Emergency](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/screens/emergency_page.dart): utility screen · Emergency information screen · `lib/screens/emergency_page.dart`

### Platform Shells

Generated host layers for each supported platform

- [Android](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/android): platform shell · Android host application wrapper · `android`
- [iOS](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/ios): platform shell · iOS host application wrapper · `ios`
- [Web](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/web): platform shell · Web host application wrapper · `web`
- [Windows](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/windows): platform shell · Windows host application wrapper · `windows`
- [macOS](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/macos): platform shell · macOS host application wrapper · `macos`
- [Linux](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/linux): platform shell · Linux host application wrapper · `linux`

### External Config

Firebase and deployment configuration boundaries

- [Firebase Options](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/lib/firebase_options.dart): firebase config · Flutter Firebase initialization settings · `lib/firebase_options.dart`
- [Firebase Hosting](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/firebase.json): deployment config · Firebase project and hosting configuration · `firebase.json`
- [Database Rules](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/database.rules.json): firebase rules · Firebase database access rules · `database.rules.json`
- [Google Services](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/blob/main/android/app/google-services.json): android firebase config · Android Firebase service configuration · `android/app/google-services.json`

### Other components

- [Images](https://github.com/samiul-hossen-sarkar-santo/bus_tracker_user_app/tree/main/assets/images): asset bundle · Route graphics and visual assets · `assets/images`

## Connections

- Main → Firebase Options: init · Initializes Firebase configuration during startup
- Main → App Shell: launches · Bootstraps the top-level app shell
- App Shell → Loading: shows · Uses loading screen during startup flow
- App Shell → Home: hosts · Primary navigation lands on the home screen
- Home → Search: searches · Routes search interaction into browsing flow
- Home → Routes List: navigates · Opens route listings from the home view
- Routes List → Route Detail: details · Drills into route detail pages
- Search → Route Detail: opens · Search results can open route details
- Route Detail → Images: renders · Displays route imagery and zoomable graphics
- Route Detail → Map: links · Can branch to map-oriented route view
- Home → Map: links · Provides access to the map screen
- Home → Emergency: links · Provides access to emergency information
- Home → Bus Catalogue: filters · Search and cards are driven by local catalogue data
- Search → Bus Catalogue: filters · Search filters route titles and stoppage names
- Routes List → Route Model: uses · Route list and detail views rely on route structure
- Route Detail → Route Model: uses · Detail page renders route metadata
- Theme State → Theme System: applies · Theme state selects the active app theme
- App Shell → Theme State: consumes · Shell reads shared theme state
- App Shell → Theme System: styles · Applies app-wide visual system
- Android → Main: hosts · Android wrapper launches the Dart app
- iOS → Main: hosts · iOS wrapper launches the Dart app
- Web → Main: hosts · Web wrapper launches the Dart app
- Windows → Main: hosts · Windows wrapper launches the Dart app
- macOS → Main: hosts · macOS wrapper launches the Dart app
- Linux → Main: hosts · Linux wrapper launches the Dart app
- Firebase Hosting → Firebase Options: pairs with · Deployment config complements app Firebase initialization
- Database Rules → Firebase Options: boundaries · Rules define the configured Firebase data boundary
- Google Services → Firebase Options: platform config · Android Firebase setup supports app initialization