# nandkishorekv/busnav architecture

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

- Interactive diagram: https://gitdiagram.com/nandkishorekv/busnav
- Repository: https://github.com/nandkishorekv/busnav

## Overview

##### What this project is (type + purpose)
From the README and the repo root contents, this is a **Flutter mobile app** (likely also capable of Flutter Web given `firebase.json`) whose purpose is **live location sharing/tracking**:

- A device **reads its GPS location** (via `location` package).
- The app **publishes the current/live coordinates to Firebase**.
- Other devices **subscribe to updates** and **render the moving position on Google Maps** (via Google Maps Flutter plugin).

The project is primarily a **client-driven architecture**: the “backend” is essentially **Firebase as a managed realtime datastore** (and possibly hosting).

##### What the file tree implies (architecture cues)
Your file tree is minimal (top-level only), but these files strongly indicate a standard Flutter app:

- `pubspec.yaml` / `pubspec.lock`: dependencies and app metadata (this is where you confirm `location`, `google_maps_flutter`, `permission_handler`, and which Firebase packages are used: e.g., `firebase_core`, `cloud_firestore` or `firebase_database`).
- `.flutter-plugins` / `.flutter-plugins-dependencies`: Flutter plugin integration → implies native platform bridges (Android/iOS) for location + maps.
- `firebase.json`: Firebase configuration for web hosting / firebase tooling. This suggests either:
- Flutter Web build + Firebase Hosting, or
- Firebase project tooling included even if mobile-only.
- `analysis_options.yaml`: lint rules (not architectural but confirms Flutter/Dart norms).

##### What to extract from README (runtime components)
The README explicitly states:
- Uses **Google Map** + **Location** package
- Writes location to **Firebase**
- “Track it live in other devices” → implies **realtime updates** (listener/stream) from Firebase

So the core runtime loop is:
##### other devices listen and update map marker/camera

This project benefits hugely from C4 because it’s “thin backend + heavy client integrations”.

##### Client-side (Flutter app on each device)

- **UI Layer**
- Screen (Google Map widget)
- Controls: “Enable live location”, “Share/Track”, etc.
- **State / Controller Layer**
- Whatever manages streams + UI updates (BLoC/Provider/SetState—confirm in `lib/`)
- **Location Service**
- Uses `location` plugin to:
- fetch current coordinates
- subscribe to continuous updates (stream)
- **Permission Manager**
- Uses `permission_handler` (or `location` built-in permission handling) to request runtime permissions
- **Firebase Data Adapter / Repository**
- Writes device location updates
- Subscribes to other device(s) location updates
- **Domain model**
- Location payload schema: `{deviceId, lat, lng, timestamp, ...}` (confirm in code)

##### External/managed services
- **Firebase**
- Be specific once you confirm the package:
- **Cloud Firestore** OR **Realtime Database**
- Holds:
- latest location per user/device
- possibly history (if implemented)
- **Google Maps Platform**
- Tiles + geospatial rendering
- Uses API keys from Google Cloud Console
- **Mobile OS services (important for accuracy)**
- Android: Fused Location Provider / Location Manager
- iOS: CoreLocation
- These are accessed indirectly via Flutter plugins, but architecturally they matter (permissions + background location constraints).

##### “Other Device(s)” (critical for live tracking)
Model at least **two clients**:
- **Publisher device** (the one sharing live location)
- **Subscriber device** (the one tracking)
They are symmetric (both run the same app), but the roles clarify data flow.

##### Permission Flow
- Flutter App → OS Permission Prompt (via permission handler)
##### Location Ingestion
- Flutter App → OS Location Services (via `location` plugin)
- returns `(lat,lng,accuracy,speed,timestamp)`
##### Publishing
- Flutter App → Firebase: `write/update location(deviceId)`
- Write frequency (e.g., on each location update)
##### Subscribing
- Flutter App ← Firebase: realtime listener/stream for `deviceId` (or group)
##### Rendering
- Flutter App → Google Maps SDK: update marker position, optionally animate camera
- Google Maps SDK ↔ Google Maps Platform: tiles/data loading

##### Non-functional flows (often missed but important)
- **Network connectivity** between device and Firebase/Google Maps
- **Auth** (if present): if using Firebase Auth, add it. If not, explicitly label “Unauthenticated / deviceId-based”.
- **Background location** (if supported): show background execution constraints + OS gating.

##### Architectural patterns likely used (and how to reflect them)
Even without seeing `lib/`, Flutter location trackers commonly follow:

- **Reactive streams**
- location updates are a stream
- firebase listeners are streams
- UI updates react to stream events
- **Repository pattern**
- `LocationRepository` / `FirebaseRepository` isolates data layer
- **Plugin boundary**
- Dart ↔ platform channels ↔ native services

##### Labels (make them concrete)
- “Flutter App (Dart)”
- “Location plugin (platform channel)”
- “Android/iOS Location Services”
- “Firebase (Firestore/Realtime DB)”
- “Google Maps SDK (flutter_google_maps plugin)”
- “Google Maps Platform APIs”
- “Permission Handler”

Examples:
- “requestPermission()”
- “locationStream()”
- “write location update”
- “subscribe to location doc/node”
- “render marker/camera update”
- “fetch map tiles”

##### How to make it maximally accurate (practical checklist)
To avoid guessing, confirm these from `pubspec.yaml` and `lib/`:
##### Data model paths
- `/locations/{deviceId}` vs `/users/{uid}/location` etc.
##### Update strategy
- continuous stream vs timer-based updates
##### Multi-user mapping
- tracking one device vs many markers
##### Auth
- anonymous auth, phone auth, none
##### Background mode
- foreground-only vs background tracking

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External Actors
  %% =========================
  UserA["User (Publisher mode)"]:::actor
  UserB["User (Subscriber mode)"]:::actor

  %% =========================
  %% Publisher Device
  %% =========================
  subgraph "Publisher Device (Mobile)"
    direction TB

    PubApp["Flutter App (Dart)"]:::client

    subgraph "App Components (Publisher)"
      direction TB
      PubUI["UI Layer\n(Map screen + Share controls)"]:::component
      PubState["State/Controller Layer\n(stream orchestration)"]:::component
      PubPerm["Permission Manager\n(runtime permissions)"]:::component
      PubLocSvc["Location Service\n(GPS stream + current fix)"]:::component
      PubRepo["Firebase Data Adapter / Repository\n(write location updates)"]:::component
      PubModel["Domain Model\n{deviceId,lat,lng,timestamp,...}"]:::component
    end

    subgraph "Flutter Plugin Bridge"
      direction TB
      PubPlugins["Platform Channels\n(Flutter plugins)"]:::plugin
      PubMeta1["Plugin Registration Metadata"]:::meta
      PubMeta2["Plugin Dependency Metadata"]:::meta
    end

    PubOS["Mobile OS Location Services\n(Android Location / iOS CoreLocation)"]:::os
    PubNet["Network Connectivity"]:::net
  end

  %% =========================
  %% Managed Cloud Services
  %% =========================
  subgraph "Managed Services (Cloud)"
    direction TB

    subgraph "Firebase"
      direction TB
      FirebaseSvc["Firebase SDK (client)"]:::cloud
      FirebaseDB[("Firebase Datastore\n(Firestore or Realtime Database)")]:::db
      FirebaseRT["Realtime Updates\n(listen/stream)"]:::cloud
      FirebaseTooling["Firebase Tooling / Hosting Config (optional)"]:::cloud
    end

    subgraph "Google Maps"
      direction TB
      MapsSDK["Google Maps SDK (Flutter plugin)\n(Map widget + markers)"]:::cloud
      MapsPlatform["Google Maps Platform APIs\n(tiles + map data)"]:::cloud
    end
  end

  %% =========================
  %% Subscriber Device
  %% =========================
  subgraph "Subscriber Device (Mobile)"
    direction TB

    SubApp["Flutter App (Dart)"]:::client

    subgraph "App Components (Subscriber)"
      direction TB
      SubUI["UI Layer\n(Map screen + Track controls)"]:::component
      SubState["State/Controller Layer\n(realtime stream -> UI)"]:::component
      SubRepo["Firebase Data Adapter / Repository\n(subscribe to locations)"]:::component
      SubModel["Domain Model\n{deviceId,lat,lng,timestamp,...}"]:::component
    end

    SubNet["Network Connectivity"]:::net
  end

  %% =========================
  %% README / Repo metadata (design cues)
  %% =========================
  subgraph "Repo Configuration & Documentation"
    direction TB
    Readme["README (architecture + usage)"]:::doc
    Pubspec["Dependencies (Flutter + plugins)"]:::doc
    Lockfile["Resolved Dependency Versions"]:::doc
    Analysis["Lint / Static Analysis Rules"]:::doc
  end

  %% =========================
  %% Flows: Publisher
  %% =========================
  UserA -->|"enableShareMode"| PubUI
  PubUI -->|"dispatchActions"| PubState
  PubState -->|"requestPermission()"| PubPerm
  PubPerm -->|"viaPlatformChannels"| PubPlugins
  PubPlugins -->|"OSPermissionPrompt"| PubOS

  PubState -->|"startLocationStream()"| PubLocSvc
  PubLocSvc -->|"viaPlatformChannels"| PubPlugins
  PubPlugins -->|"readGPSUpdates"| PubOS
  PubLocSvc -->|"emitLocationUpdate"| PubState
  PubState -->|"mapToModel"| PubModel
  PubState -->|"writeLocationUpdate"| PubRepo

  PubRepo -->|"clientSDKCalls"| FirebaseSvc
  PubNet -->|"HTTPS/WebSocket"| FirebaseSvc
  FirebaseSvc -->|"write/update /locations/{deviceId}"| FirebaseDB

  %% =========================
  %% Flows: Subscriber
  %% =========================
  UserB -->|"enableTrackMode"| SubUI
  SubUI -->|"dispatchActions"| SubState
  SubState -->|"subscribeToDeviceLocation"| SubRepo
  SubRepo -->|"clientSDKCalls"| FirebaseSvc
  SubNet -->|"HTTPS/WebSocket"| FirebaseSvc
  FirebaseDB -->|"realtimeChangeFeed"| FirebaseRT
  FirebaseRT -->|"locationStream()"| SubRepo
  SubRepo -->|"mapToModel"| SubModel
  SubRepo -->|"emitUpdates"| SubState
  SubState -->|"renderMarkerAndCameraUpdates"| SubUI

  %% =========================
  %% Maps rendering + external APIs
  %% =========================
  PubUI -->|"renderMap/marker"| MapsSDK
  SubUI -->|"renderMap/marker"| MapsSDK
  MapsSDK -->|"fetchMapTilesAndData"| MapsPlatform

  %% =========================
  %% Firebase tooling / web hosting cue
  %% =========================
  FirebaseTooling -.->|"configuredBy"| FirebaseSvc

  %% =========================
  %% Documentation references (non-runtime)
  %% =========================
  Readme -.->|"describesLiveTrackingFlow"| PubApp
  Readme -.->|"describesLiveTrackingFlow"| SubApp
  Pubspec -.->|"declaresPluginsAndFirebasePkgs"| PubApp
  Lockfile -.->|"pinsVersions"| Pubspec
  Analysis -.->|"lintRules"| PubApp

  %% =========================
  %% Click Events (component_mapping)
  %% =========================
  click Pubspec "https://github.com/nandkishorekv/busnav/blob/main/pubspec.yaml"
  click Lockfile "https://github.com/nandkishorekv/busnav/blob/main/pubspec.lock"
  click PubMeta1 "https://github.com/nandkishorekv/busnav/blob/main/.flutter-plugins"
  click PubMeta2 "https://github.com/nandkishorekv/busnav/blob/main/.flutter-plugins-dependencies"
  click FirebaseTooling "https://github.com/nandkishorekv/busnav/blob/main/firebase.json"
  click Readme "https://github.com/nandkishorekv/busnav/blob/main/README.md"
  click Analysis "https://github.com/nandkishorekv/busnav/blob/main/analysis_options.yaml"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px,color:#1B5E20
  classDef client fill:#E3F2FD,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1
  classDef component fill:#BBDEFB,stroke:#1E88E5,stroke-width:1px,color:#0D47A1
  classDef plugin fill:#D1C4E9,stroke:#5E35B1,stroke-width:1px,color:#311B92
  classDef os fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238
  classDef cloud fill:#FFE0B2,stroke:#EF6C00,stroke-width:1.5px,color:#E65100
  classDef db fill:#FFD180,stroke:#FB8C00,stroke-width:1.5px,color:#E65100
  classDef net fill:#F5F5F5,stroke:#757575,stroke-width:1px,color:#424242
  classDef doc fill:#FFF9C4,stroke:#F9A825,stroke-width:1px,color:#6D4C41
  classDef meta fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px,color:#4A148C
```
