# nickyyayy/wheresmybus architecture

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

- Interactive diagram: https://gitdiagram.com/nickyyayy/wheresmybus
- Repository: https://github.com/nickyyayy/wheresmybus

## Overview

WheresMyBus is a hardware-independent campus bus tracker: conductors report stop arrivals, the system validates and applies route progress, and students and supervisors view bus status and statistics. At startup, the C++ application loads routes and buses from MySQL, creates dashboard pages, then serves a web bridge or offers a console mode. The graph preserves the documented student, conductor, and supervisor interfaces. Some implementation links are omitted because the relevant source was not excerpted; dashed edges indicate documented or unverified relationships.

Main entry points: [`backend/BusStatusEngine.cpp`](https://github.com/nickyyayy/wheresmybus/blob/main/backend/BusStatusEngine.cpp) (Status engine), [`backend/main.cpp`](https://github.com/nickyyayy/wheresmybus/blob/main/backend/main.cpp) (Application startup), [`backend/DataLoader.cpp`](https://github.com/nickyyayy/wheresmybus/blob/main/backend/DataLoader.cpp) (Domain data loader), [`backend/HtmlGenerator.cpp`](https://github.com/nickyyayy/wheresmybus/blob/main/backend/HtmlGenerator.cpp) (Dashboard generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and data"]
  node_app["Application startup<br/>[main.cpp]"]
  node_database[("MySQL access<br/>[Database.cpp]")]
  node_loader["Domain data loader<br/>[DataLoader.cpp]"]
end

subgraph group_routes["Route model"]
  node_route_registry["Route registry<br/>[RouteRegistry.cpp]"]
  node_route["Route sequence<br/>[Route.cpp]"]
  node_route_node["Route stop node<br/>[RouteStopNode.cpp]"]
  node_stop["Stop model<br/>[Stop.cpp]"]
  node_validation["Route validation"]
end

subgraph group_operations["Bus operations"]
  node_bus_registry["Bus registry<br/>[BusRegistry.cpp]"]
  node_bus["Bus state<br/>[Bus.cpp]"]
  node_engine["Status engine"]
  node_update["Update records<br/>[Update.cpp]"]
  node_queue["Pending updates<br/>[Queue.h]"]
  node_history["Update history<br/>[Stack.h]"]
end

subgraph group_interfaces["User interfaces"]
  node_html["Dashboard generator<br/>[HtmlGenerator.cpp]"]
  node_web["Web bridge<br/>[WebBridge.cpp]"]
  node_console["Console interface<br/>[ConsoleMenu.cpp]"]
end

node_student(("Student"))
node_conductor(("Conductor"))
node_supervisor(("Supervisor"))

node_app -->|"connects to"| node_database
node_app -->|"loads data"| node_loader
node_app -->|"initializes"| node_engine
node_app -->|"generates pages"| node_html
node_app -->|"starts web mode"| node_web
node_app -->|"starts CLI mode"| node_console
node_loader -.->|"reads MySQL"| node_database
node_loader -.->|"loads routes"| node_route_registry
node_loader -.->|"loads buses"| node_bus_registry
node_route_registry -->|"owns routes"| node_route
node_route -->|"links stops"| node_route_node
node_route_node -->|"models stop"| node_stop
node_bus_registry -->|"owns buses"| node_bus
node_engine -->|"looks up routes"| node_route_registry
node_engine -->|"looks up buses"| node_bus_registry
node_engine -->|"validates positions"| node_validation
node_engine -->|"applies updates"| node_update
node_engine -->|"queues updates"| node_queue
node_engine -->|"records history"| node_history
node_html -->|"reads bus state"| node_engine
node_student -.->|"views status"| node_html
node_conductor -.->|"reports progress"| node_engine
node_supervisor -.->|"views statistics"| node_html

click node_app "https://github.com/nickyyayy/wheresmybus/blob/main/backend/main.cpp"
click node_database "https://github.com/nickyyayy/wheresmybus/blob/main/backend/Database.cpp"
click node_loader "https://github.com/nickyyayy/wheresmybus/blob/main/backend/DataLoader.cpp"
click node_route_registry "https://github.com/nickyyayy/wheresmybus/blob/main/backend/RouteRegistry.cpp"
click node_route "https://github.com/nickyyayy/wheresmybus/blob/main/backend/Route.cpp"
click node_route_node "https://github.com/nickyyayy/wheresmybus/blob/main/backend/RouteStopNode.cpp"
click node_stop "https://github.com/nickyyayy/wheresmybus/blob/main/backend/Stop.cpp"
click node_validation "https://github.com/nickyyayy/wheresmybus/blob/main/backend/RouteValidation.cpp"
click node_bus_registry "https://github.com/nickyyayy/wheresmybus/blob/main/backend/BusRegistry.cpp"
click node_bus "https://github.com/nickyyayy/wheresmybus/blob/main/backend/Bus.cpp"
click node_engine "https://github.com/nickyyayy/wheresmybus/blob/main/backend/BusStatusEngine.cpp"
click node_update "https://github.com/nickyyayy/wheresmybus/blob/main/backend/Update.cpp"
click node_queue "https://github.com/nickyyayy/wheresmybus/blob/main/backend/Queue.h"
click node_history "https://github.com/nickyyayy/wheresmybus/blob/main/backend/Stack.h"
click node_html "https://github.com/nickyyayy/wheresmybus/blob/main/backend/HtmlGenerator.cpp"
click node_web "https://github.com/nickyyayy/wheresmybus/blob/main/backend/WebBridge.cpp"
click node_console "https://github.com/nickyyayy/wheresmybus/blob/main/backend/ConsoleMenu.cpp"

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_app,node_database,node_loader toneBlue
class node_route_registry,node_route,node_route_node,node_stop,node_validation toneAmber
class node_bus_registry,node_bus,node_engine,node_update,node_queue,node_history toneMint
class node_html,node_web,node_console toneRose
class node_student,node_conductor,node_supervisor toneIndigo
```

## Components

### Startup and data

- [Application startup](https://github.com/nickyyayy/wheresmybus/blob/main/backend/main.cpp): `backend/main.cpp`
- [MySQL access](https://github.com/nickyyayy/wheresmybus/blob/main/backend/Database.cpp): `backend/Database.cpp`
- [Domain data loader](https://github.com/nickyyayy/wheresmybus/blob/main/backend/DataLoader.cpp): `backend/DataLoader.cpp`

### Route model

- [Route registry](https://github.com/nickyyayy/wheresmybus/blob/main/backend/RouteRegistry.cpp): `backend/RouteRegistry.cpp`
- [Route sequence](https://github.com/nickyyayy/wheresmybus/blob/main/backend/Route.cpp): `backend/Route.cpp`
- [Route stop node](https://github.com/nickyyayy/wheresmybus/blob/main/backend/RouteStopNode.cpp): `backend/RouteStopNode.cpp`
- [Stop model](https://github.com/nickyyayy/wheresmybus/blob/main/backend/Stop.cpp): `backend/Stop.cpp`
- [Route validation](https://github.com/nickyyayy/wheresmybus/blob/main/backend/RouteValidation.cpp): `backend/RouteValidation.cpp`

### Bus operations

- [Bus registry](https://github.com/nickyyayy/wheresmybus/blob/main/backend/BusRegistry.cpp): `backend/BusRegistry.cpp`
- [Bus state](https://github.com/nickyyayy/wheresmybus/blob/main/backend/Bus.cpp): `backend/Bus.cpp`
- [Status engine](https://github.com/nickyyayy/wheresmybus/blob/main/backend/BusStatusEngine.cpp): `backend/BusStatusEngine.cpp`
- [Update records](https://github.com/nickyyayy/wheresmybus/blob/main/backend/Update.cpp): `backend/Update.cpp`
- [Pending updates](https://github.com/nickyyayy/wheresmybus/blob/main/backend/Queue.h): `backend/Queue.h`
- [Update history](https://github.com/nickyyayy/wheresmybus/blob/main/backend/Stack.h): `backend/Stack.h`

### User interfaces

- [Dashboard generator](https://github.com/nickyyayy/wheresmybus/blob/main/backend/HtmlGenerator.cpp): `backend/HtmlGenerator.cpp`
- [Web bridge](https://github.com/nickyyayy/wheresmybus/blob/main/backend/WebBridge.cpp): `backend/WebBridge.cpp`
- [Console interface](https://github.com/nickyyayy/wheresmybus/blob/main/backend/ConsoleMenu.cpp): `backend/ConsoleMenu.cpp`

### Other components

- **Student**
- **Conductor**
- **Supervisor**

## Connections

- Application startup → MySQL access: connects to (evidence: `backend/main.cpp`)
- Application startup → Domain data loader: loads data (evidence: `backend/main.cpp`)
- Application startup → Status engine: initializes (evidence: `backend/main.cpp`)
- Application startup → Dashboard generator: generates pages (evidence: `backend/main.cpp`)
- Application startup → Web bridge: starts web mode (evidence: `backend/main.cpp`)
- Application startup → Console interface: starts CLI mode (evidence: `backend/main.cpp`)
- Domain data loader → MySQL access: reads MySQL
- Domain data loader → Route registry: loads routes
- Domain data loader → Bus registry: loads buses
- Route registry → Route sequence: owns routes
- Route sequence → Route stop node: links stops
- Route stop node → Stop model: models stop
- Bus registry → Bus state: owns buses
- Status engine → Route registry: looks up routes (evidence: `backend/BusStatusEngine.cpp`)
- Status engine → Bus registry: looks up buses (evidence: `backend/BusStatusEngine.cpp`)
- Status engine → Route validation: validates positions (evidence: `backend/BusStatusEngine.cpp`)
- Status engine → Update records: applies updates (evidence: `backend/BusStatusEngine.cpp`)
- Status engine → Pending updates: queues updates (evidence: `backend/BusStatusEngine.cpp`)
- Status engine → Update history: records history (evidence: `backend/BusStatusEngine.cpp`)
- Dashboard generator → Status engine: reads bus state
- Student → Dashboard generator: views status (evidence: `README.md`)
- Conductor → Status engine: reports progress (evidence: `README.md`)
- Supervisor → Dashboard generator: views statistics (evidence: `README.md`)
