# blessonnn/bus-tracking architecture

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

- Interactive diagram: https://gitdiagram.com/blessonnn/bus-tracking
- Repository: https://github.com/blessonnn/bus-tracking

## Overview

1. This is a Next.js App Router frontend for a college bus tracking system. The repository is almost entirely UI-centric: route pages live under `app/`, shared shell components live under `components/`, and there is no local API layer or server-side domain code in the tree.

2. The application is organized around three user roles: student, driver, and admin. Each role has its own dashboard subtree under `app/dashboard/...`, which strongly suggests role-based navigation and separate feature surfaces rather than a single generic dashboard.

3. The top-level navigation flow is simple: the root page likely lands on a public entry screen, `/login` handles authentication entry, and authenticated users are routed into one of the role dashboards. The presence of a `login/loading.tsx` indicates Next.js route-level loading/suspense handling for that entry path.

4. The dashboard UI is centralized through `components/dashboard-layout.tsx`. That component is the key shared shell boundary for authenticated screens, likely providing common chrome such as sidebar, header, navigation, and responsive layout across the admin/driver/student areas.

5. Each role subtree contains page-level slices of functionality:
   - Student: dashboard, routes, notifications, settings
   - Driver: dashboard, routes, profile, settings
   - Admin: dashboard, buses, drivers, settings  
   This maps the product into three distinct operational views: ride consumption, route operation, and fleet administration.

6. The `components/map.tsx` file is an important subsystem boundary because tracking systems usually depend on geospatial rendering. Combined with the README environment variable `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY`, this indicates external map services are part of the client-side architecture, probably used in route or live tracking pages.

7. There is no dedicated state-management or data-access folder, which suggests the pages and shared components are likely reading data directly from external services or mocked/local state within the UI layer. The `NEXT_PUBLIC_API_URL` variable in the README implies the frontend expects a separate backend service for auth, buses, drivers, routes, notifications, and live tracking data.

8. UI composition is built on a reusable design system under `components/ui/`, with shadcn-style primitives such as buttons, cards, dialogs, tables, forms, tabs, sheets, and sidebars. This makes the visual architecture highly componentized and indicates that most page complexity is assembled from shared primitives rather than custom widgets.

9. Theme and device adaptation are explicit cross-cutting concerns. `components/theme-provider.tsx`, `hooks/use-mobile.tsx`, and `components/ui/use-mobile.tsx` suggest client-side responsiveness and theme switching are handled centrally and consumed by the dashboards and shared layout.

10. Styling is split across `app/globals.css`, `styles/globals.css`, `tailwind.config.ts`, and PostCSS config. The project uses Tailwind-driven styling with global CSS layers, so the visual system is mostly utility-based with a small amount of global baseline styling.

11. The repository is configured for Next.js + TypeScript + npm, with root-level `next.config.mjs`, `tsconfig.json`, and lockfiles. This is a single frontend deployment unit that can be built and served independently, typically behind a separate backend and external map provider.

12. `scripts/download-markers.js` hints at an asset preparation step related to map markers or tracking icons. That suggests some visualization assets are generated or fetched ahead of time rather than hardcoded in page components.

13. The most important architectural boundary for a diagram is: routed pages in `app/` compose shared UI in `components/`, which in turn depend on client-side utilities, styling, and external services. The external dependencies are the backend API and Google Maps; everything else in the repo is presentation, routing, and UI reuse.

Main entry points: [`components/dashboard-layout.tsx`](https://github.com/blessonnn/bus-tracking/blob/main/components/dashboard-layout.tsx) (Dashboard shell), [`components/map.tsx`](https://github.com/blessonnn/bus-tracking/blob/main/components/map.tsx) (Map), [`app/dashboard/student/routes/page.tsx`](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/student/routes/page.tsx) (Student routes), [`app/dashboard/driver/routes/page.tsx`](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/driver/routes/page.tsx) (Driver routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App routes"]
  node_root_page["Home<br/>route page<br/>[page.tsx]"]
  node_login_page["Login<br/>route page<br/>[page.tsx]"]
  node_login_loading["Login loading<br/>route state<br/>[loading.tsx]"]
  node_student_dashboard["Student home<br/>route page<br/>[page.tsx]"]
  node_student_routes["Student routes<br/>route page<br/>[page.tsx]"]
  node_student_notifications["Notifications<br/>route page<br/>[page.tsx]"]
  node_student_settings["Student settings<br/>route page<br/>[page.tsx]"]
  node_driver_dashboard["Driver home<br/>route page<br/>[page.tsx]"]
  node_driver_routes["Driver routes<br/>route page<br/>[page.tsx]"]
  node_driver_profile["Profile<br/>route page<br/>[page.tsx]"]
  node_driver_settings["Driver settings<br/>route page<br/>[page.tsx]"]
  node_admin_dashboard["Admin home<br/>route page<br/>[page.tsx]"]
  node_admin_buses["Buses<br/>route page<br/>[page.tsx]"]
  node_admin_drivers["Drivers<br/>route page<br/>[page.tsx]"]
  node_admin_settings["Admin settings<br/>route page<br/>[page.tsx]"]
end

subgraph group_components["Shared UI"]
  node_dashboard_layout["Dashboard shell<br/>shared layout"]
  node_map_component{{"Map<br/>[map.tsx]"}}
  node_theme_provider["Theme provider<br/>client theme<br/>[theme-provider.tsx]"]
  node_ui_kit["UI kit<br/>design system"]
  node_mobile_hook["Mobile hook<br/>responsive hook<br/>[use-mobile.tsx]"]
end

subgraph group_infra["Styling & tooling"]
  node_utils["Utils<br/>shared helpers<br/>[utils.ts]"]
  node_globals_css["Global styles<br/>styling<br/>[globals.css]"]
  node_styles_css["Style sheet<br/>styling<br/>[globals.css]"]
  node_tailwind_config["Tailwind config<br/>build config<br/>[tailwind.config.ts]"]
  node_marker_script["Marker script<br/>asset script"]
end

subgraph group_external["External services"]
  node_backend_api[("Backend API<br/>external backend")]
  node_google_maps(("Google Maps<br/>external maps"))
end

node_root_page -->|"entry"| node_login_page
node_login_page -->|"suspense"| node_login_loading
node_login_page -->|"auth shell"| node_dashboard_layout
node_student_dashboard -->|"uses"| node_dashboard_layout
node_student_routes -->|"uses"| node_dashboard_layout
node_student_notifications -->|"uses"| node_dashboard_layout
node_student_settings -->|"uses"| node_dashboard_layout
node_driver_dashboard -->|"uses"| node_dashboard_layout
node_driver_routes -->|"uses"| node_dashboard_layout
node_driver_profile -->|"uses"| node_dashboard_layout
node_driver_settings -->|"uses"| node_dashboard_layout
node_admin_dashboard -->|"uses"| node_dashboard_layout
node_admin_buses -->|"uses"| node_dashboard_layout
node_admin_drivers -->|"uses"| node_dashboard_layout
node_admin_settings -->|"uses"| node_dashboard_layout
node_dashboard_layout -->|"composes"| node_ui_kit
node_dashboard_layout -->|"adapts"| node_mobile_hook
node_dashboard_layout -->|"themes"| node_theme_provider
node_student_routes -->|"tracks"| node_map_component
node_driver_routes -->|"tracks"| node_map_component
node_map_component -->|"depends on"| node_google_maps
node_student_dashboard -.->|"data"| node_backend_api
node_driver_dashboard -.->|"data"| node_backend_api
node_admin_dashboard -.->|"data"| node_backend_api
node_student_routes -.->|"data"| node_backend_api
node_driver_routes -.->|"data"| node_backend_api
node_admin_buses -.->|"data"| node_backend_api
node_admin_drivers -.->|"data"| node_backend_api
node_ui_kit -->|"helpers"| node_utils
node_globals_css -->|"styled by"| node_tailwind_config
node_styles_css -->|"styled by"| node_tailwind_config
node_marker_script -.->|"assets for"| node_map_component

click node_root_page "https://github.com/blessonnn/bus-tracking/blob/main/app/page.tsx"
click node_login_page "https://github.com/blessonnn/bus-tracking/blob/main/app/login/page.tsx"
click node_login_loading "https://github.com/blessonnn/bus-tracking/blob/main/app/login/loading.tsx"
click node_student_dashboard "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/student/page.tsx"
click node_student_routes "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/student/routes/page.tsx"
click node_student_notifications "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/student/notifications/page.tsx"
click node_student_settings "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/student/settings/page.tsx"
click node_driver_dashboard "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/driver/page.tsx"
click node_driver_routes "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/driver/routes/page.tsx"
click node_driver_profile "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/driver/profile/page.tsx"
click node_driver_settings "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/driver/settings/page.tsx"
click node_admin_dashboard "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/admin/page.tsx"
click node_admin_buses "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/admin/buses/page.tsx"
click node_admin_drivers "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/admin/drivers/page.tsx"
click node_admin_settings "https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/admin/settings/page.tsx"
click node_dashboard_layout "https://github.com/blessonnn/bus-tracking/blob/main/components/dashboard-layout.tsx"
click node_map_component "https://github.com/blessonnn/bus-tracking/blob/main/components/map.tsx"
click node_theme_provider "https://github.com/blessonnn/bus-tracking/blob/main/components/theme-provider.tsx"
click node_ui_kit "https://github.com/blessonnn/bus-tracking/tree/main/components/ui"
click node_mobile_hook "https://github.com/blessonnn/bus-tracking/blob/main/hooks/use-mobile.tsx"
click node_utils "https://github.com/blessonnn/bus-tracking/blob/main/lib/utils.ts"
click node_globals_css "https://github.com/blessonnn/bus-tracking/blob/main/app/globals.css"
click node_styles_css "https://github.com/blessonnn/bus-tracking/blob/main/styles/globals.css"
click node_tailwind_config "https://github.com/blessonnn/bus-tracking/blob/main/tailwind.config.ts"
click node_marker_script "https://github.com/blessonnn/bus-tracking/blob/main/scripts/download-markers.js"

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_root_page,node_login_page,node_login_loading,node_student_dashboard,node_student_routes,node_student_notifications,node_student_settings,node_driver_dashboard,node_driver_routes,node_driver_profile,node_driver_settings,node_admin_dashboard,node_admin_buses,node_admin_drivers,node_admin_settings toneBlue
class node_dashboard_layout,node_map_component,node_theme_provider,node_ui_kit,node_mobile_hook toneAmber
class node_utils,node_globals_css,node_styles_css,node_tailwind_config,node_marker_script toneMint
class node_backend_api,node_google_maps toneRose
```

## Components

### App routes

Next.js App Router pages and route-level screens.

- [Home](https://github.com/blessonnn/bus-tracking/blob/main/app/page.tsx): route page · Public entry screen for the app. · `app/page.tsx`
- [Login](https://github.com/blessonnn/bus-tracking/blob/main/app/login/page.tsx): route page · Authentication entry page. · `app/login/page.tsx`
- [Login loading](https://github.com/blessonnn/bus-tracking/blob/main/app/login/loading.tsx): route state · Route-level loading UI for the login path. · `app/login/loading.tsx`
- [Student home](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/student/page.tsx): route page · Student landing dashboard. · `app/dashboard/student/page.tsx`
- [Student routes](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/student/routes/page.tsx): route page · Student view for bus routes and tracking. · `app/dashboard/student/routes/page.tsx`
- [Notifications](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/student/notifications/page.tsx): route page · Student notifications screen. · `app/dashboard/student/notifications/page.tsx`
- [Student settings](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/student/settings/page.tsx): route page · Student account and preference settings. · `app/dashboard/student/settings/page.tsx`
- [Driver home](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/driver/page.tsx): route page · Driver landing dashboard. · `app/dashboard/driver/page.tsx`
- [Driver routes](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/driver/routes/page.tsx): route page · Driver route operation screen. · `app/dashboard/driver/routes/page.tsx`
- [Profile](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/driver/profile/page.tsx): route page · Driver profile management screen. · `app/dashboard/driver/profile/page.tsx`
- [Driver settings](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/driver/settings/page.tsx): route page · Driver account and preference settings. · `app/dashboard/driver/settings/page.tsx`
- [Admin home](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/admin/page.tsx): route page · Admin landing dashboard. · `app/dashboard/admin/page.tsx`
- [Buses](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/admin/buses/page.tsx): route page · Fleet bus management screen. · `app/dashboard/admin/buses/page.tsx`
- [Drivers](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/admin/drivers/page.tsx): route page · Driver administration screen. · `app/dashboard/admin/drivers/page.tsx`
- [Admin settings](https://github.com/blessonnn/bus-tracking/blob/main/app/dashboard/admin/settings/page.tsx): route page · Admin account and system settings. · `app/dashboard/admin/settings/page.tsx`

### Shared UI

Reusable shell, map, theme, and design-system components.

- [Dashboard shell](https://github.com/blessonnn/bus-tracking/blob/main/components/dashboard-layout.tsx): shared layout · Common authenticated layout for role dashboards. · `components/dashboard-layout.tsx`
- [Map](https://github.com/blessonnn/bus-tracking/blob/main/components/map.tsx): client map · Geospatial visualization component for tracking and routes. · `components/map.tsx`
- [Theme provider](https://github.com/blessonnn/bus-tracking/blob/main/components/theme-provider.tsx): client theme · Central theme switching and theming context. · `components/theme-provider.tsx`
- [UI kit](https://github.com/blessonnn/bus-tracking/tree/main/components/ui): design system · Reusable shadcn-style primitives used across screens. · `components/ui`
- [Mobile hook](https://github.com/blessonnn/bus-tracking/blob/main/hooks/use-mobile.tsx): responsive hook · Client-side mobile breakpoint detection. · `hooks/use-mobile.tsx`

### Styling & tooling

Global styling, utilities, and repo-level build scripts.

- [Utils](https://github.com/blessonnn/bus-tracking/blob/main/lib/utils.ts): shared helpers · Common utility helpers for the UI layer. · `lib/utils.ts`
- [Global styles](https://github.com/blessonnn/bus-tracking/blob/main/app/globals.css): styling · Global CSS baseline for the app. · `app/globals.css`
- [Style sheet](https://github.com/blessonnn/bus-tracking/blob/main/styles/globals.css): styling · Additional global styling layer. · `styles/globals.css`
- [Tailwind config](https://github.com/blessonnn/bus-tracking/blob/main/tailwind.config.ts): build config · Tailwind theme and utility configuration. · `tailwind.config.ts`
- [Marker script](https://github.com/blessonnn/bus-tracking/blob/main/scripts/download-markers.js): asset script · Prepares or downloads map marker assets. · `scripts/download-markers.js`

### External services

Backend and third-party services the frontend depends on.

- **Backend API**: external backend · Separate service for auth, buses, drivers, routes, notifications, and tracking.
- **Google Maps**: external maps · Third-party map provider used by the client map UI.

## Connections

- Home → Login: entry · Public landing routes users toward authentication.
- Login → Login loading: suspense · Login route uses route-level loading UI.
- Login → Dashboard shell: auth shell · Authenticated users transition into the shared dashboard shell.
- Student home → Dashboard shell: uses · Student screens share the common dashboard layout.
- Student routes → Dashboard shell: uses · Student route screens are rendered inside the dashboard shell.
- Notifications → Dashboard shell: uses · Student notifications screen uses the shared shell.
- Student settings → Dashboard shell: uses · Student settings screen uses the shared shell.
- Driver home → Dashboard shell: uses · Driver screens share the common dashboard layout.
- Driver routes → Dashboard shell: uses · Driver route screens are rendered inside the dashboard shell.
- Profile → Dashboard shell: uses · Driver profile screen uses the shared shell.
- Driver settings → Dashboard shell: uses · Driver settings screen uses the shared shell.
- Admin home → Dashboard shell: uses · Admin screens share the common dashboard layout.
- Buses → Dashboard shell: uses · Admin bus management screen uses the shared shell.
- Drivers → Dashboard shell: uses · Admin driver management screen uses the shared shell.
- Admin settings → Dashboard shell: uses · Admin settings screen uses the shared shell.
- Dashboard shell → UI kit: composes · The shell is built from reusable UI primitives.
- Dashboard shell → Mobile hook: adapts · Layout behavior adapts to mobile breakpoints.
- Dashboard shell → Theme provider: themes · Dashboard UI consumes shared theme context.
- Student routes → Map: tracks · Route views likely render live or static map tracking.
- Driver routes → Map: tracks · Driver route operation views likely use the map component.
- Map → Google Maps: depends on · Client map rendering is backed by Google Maps.
- Student home → Backend API: data · Role dashboards depend on the external backend for operational data.
- Driver home → Backend API: data · Role dashboards depend on the external backend for operational data.
- Admin home → Backend API: data · Role dashboards depend on the external backend for operational data.
- Student routes → Backend API: data · Route and tracking screens depend on backend data.
- Driver routes → Backend API: data · Route and tracking screens depend on backend data.
- Buses → Backend API: data · Fleet management screens depend on backend data.
- Drivers → Backend API: data · Fleet management screens depend on backend data.
- UI kit → Utils: helpers · Shared primitives rely on common helper utilities.
- Global styles → Tailwind config: styled by · Global styles are shaped by Tailwind configuration.
- Style sheet → Tailwind config: styled by · Additional styles are shaped by Tailwind configuration.
- Marker script → Map: assets for · Prepared markers support the map visualization subsystem.
