How blessonnn/bus-tracking works
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: dashboard-layout.tsx Dashboard shell · map.tsx Map · routes/page.tsx Student routes · routes/page.tsx Driver routes
Components 27
App routes
Next.js App Router pages and route-level screens.
- Home · Public entry screen for the app.
app/page.tsx - Login · Authentication entry page.
app/login/page.tsx - Login loading · Route-level loading UI for the login path.
app/login/loading.tsx - Student home · Student landing dashboard.
app/dashboard/student/page.tsx - Student routes · Student view for bus routes and tracking.
app/dashboard/student/routes/page.tsx - Notifications · Student notifications screen.
app/dashboard/student/notifications/page.tsx - Student settings · Student account and preference settings.
app/dashboard/student/settings/page.tsx - Driver home · Driver landing dashboard.
app/dashboard/driver/page.tsx - Driver routes · Driver route operation screen.
app/dashboard/driver/routes/page.tsx - Profile · Driver profile management screen.
app/dashboard/driver/profile/page.tsx - Driver settings · Driver account and preference settings.
app/dashboard/driver/settings/page.tsx - Admin home · Admin landing dashboard.
app/dashboard/admin/page.tsx - Buses · Fleet bus management screen.
app/dashboard/admin/buses/page.tsx - Drivers · Driver administration screen.
app/dashboard/admin/drivers/page.tsx - Admin settings · Admin account and system settings.
app/dashboard/admin/settings/page.tsx
Shared UI
Reusable shell, map, theme, and design-system components.
- Dashboard shell · Common authenticated layout for role dashboards.
components/dashboard-layout.tsx - Map · Geospatial visualization component for tracking and routes.
components/map.tsx - Theme provider · Central theme switching and theming context.
components/theme-provider.tsx - UI kit · Reusable shadcn-style primitives used across screens.
components/ui - Mobile hook · Client-side mobile breakpoint detection.
hooks/use-mobile.tsx
Styling & tooling
Global styling, utilities, and repo-level build scripts.
- Utils · Common utility helpers for the UI layer.
lib/utils.ts - Global styles · Global CSS baseline for the app.
app/globals.css - Style sheet · Additional global styling layer.
styles/globals.css - Tailwind config · Tailwind theme and utility configuration.
tailwind.config.ts - Marker script · Prepares or downloads map marker assets.
scripts/download-markers.js
External services
Backend and third-party services the frontend depends on.
- Backend API · Separate service for auth, buses, drivers, routes, notifications, and tracking.
- Google Maps · Third-party map provider used by the client map UI.
Connections 32
- 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.