# milesjdantonio/hokiebikerack architecture

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

- Interactive diagram: https://gitdiagram.com/milesjdantonio/hokiebikerack
- Repository: https://github.com/milesjdantonio/hokiebikerack

## Overview

HokieBikeRack combines a locally operating Arduino rack, a Spring Boot administration backend, and browser interfaces for rider, staff, police, and admin roles. The real Uno enrolls cards locally and reports events over serial; it does not connect to the backend. The principal demo workflow uses a simulated rack with the backend and dashboard. The browser firmware model separately runs the real firmware logic. Several backend controllers and frontend modules were not excerpted, so uncertain links are omitted or marked unverified.

Main entry points: [`firmware/src/main.cpp`](https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/src/main.cpp) (Arduino Rack), [`backend/src/main/java/edu/vt/hokiebikerack/events/EventService.java`](https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/events/EventService.java) (Event Ingestion), [`frontend/js/api.js`](https://github.com/milesjdantonio/hokiebikerack/blob/main/frontend/js/api.js) (Browser API Client), [`backend/src/main/java/edu/vt/hokiebikerack/audit/AuditService.java`](https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/audit/AuditService.java) (Audit Log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rack["Rack Firmware"]
  node_rack_hw["Arduino Rack<br/>[main.cpp]"]
  node_card_access["Card Access<br/>[card_reader.cpp]"]
  node_card_store[("EEPROM Cards<br/>[card_store.cpp]")]
  node_lock_feedback["Lock &amp; Feedback<br/>[lock.cpp]"]
  node_tamper["Tamper Detection<br/>[tamper_detector.h]"]
end

subgraph group_backend["Backend Services"]
  node_rack_api["Rack Management<br/>[RackService.java]"]
  node_device_api["Device Authentication"]
  node_event_api["Event Ingestion<br/>[EventService.java]"]
  node_incident_api["Incident Workflow"]
  node_rider_api["Rider &amp; Cards<br/>[RiderService.java]"]
  node_reports["Reports<br/>[ReportService.java]"]
end

subgraph group_web["Browser Applications"]
  node_dashboard["Role Dashboards<br/>[console.js]"]
  node_rider_ui["Rider Interface<br/>[rider.js]"]
  node_campus_map["Campus Map<br/>[map.js]"]
  node_browser_api["Browser API Client<br/>[api.js]"]
end

subgraph group_simulation["Simulation"]
  node_firmware_model["Firmware Model<br/>[model_api.cpp]"]
  node_model_ui["Model Interface<br/>[app.js]"]
  node_simulator["Device Simulator"]
end

subgraph group_shared["Shared Services"]
  node_audit[("Audit Log<br/>[AuditService.java]")]
  node_database[("PostgreSQL")]
end

node_rider(("Rider"))
node_staff(("Staff / Admin"))
node_police(("Police"))

node_rider -->|"taps card"| node_rack_hw
node_rack_hw -->|"polls reader"| node_card_access
node_rack_hw -->|"checks / enrolls"| node_card_store
node_rack_hw -->|"controls outputs"| node_lock_feedback
node_rack_hw -->|"checks motion"| node_tamper
node_rack_hw -->|"prints serial events"| node_staff
node_staff -->|"uses dashboard"| node_dashboard
node_police -->|"uses dashboard"| node_dashboard
node_rider -->|"uses rider view"| node_rider_ui
node_dashboard -->|"calls API client"| node_browser_api
node_rider_ui -.->|"uses API client"| node_browser_api
node_dashboard -->|"renders map"| node_campus_map
node_browser_api -.->|"requests backend"| node_rack_api
node_browser_api -.->|"requests backend"| node_event_api
node_browser_api -.->|"requests backend"| node_rider_api
node_simulator -.->|"simulates rack"| node_device_api
node_device_api -->|"authenticates device"| node_event_api
node_event_api -->|"publishes refusal"| node_incident_api
node_rack_api -->|"records changes"| node_audit
node_event_api -->|"records changes"| node_audit
node_incident_api -->|"records changes"| node_audit
node_rider_api -->|"records changes"| node_audit
node_rack_api -->|"reads / writes"| node_database
node_event_api -->|"reads / writes"| node_database
node_incident_api -->|"reads / writes"| node_database
node_rider_api -->|"reads / writes"| node_database
node_reports -->|"queries reports"| node_database
node_audit -->|"stores audit entries"| node_database
node_model_ui -->|"boots / steps"| node_firmware_model
node_firmware_model -->|"runs firmware"| node_rack_hw

click node_rack_hw "https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/src/main.cpp"
click node_card_access "https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/src/card_reader.cpp"
click node_card_store "https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/src/card_store.cpp"
click node_lock_feedback "https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/src/lock.cpp"
click node_tamper "https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/lib/hbr_logic/src/tamper_detector.h"
click node_dashboard "https://github.com/milesjdantonio/hokiebikerack/blob/main/frontend/shared/console.js"
click node_rider_ui "https://github.com/milesjdantonio/hokiebikerack/blob/main/frontend/shared/rider.js"
click node_campus_map "https://github.com/milesjdantonio/hokiebikerack/blob/main/frontend/shared/map.js"
click node_browser_api "https://github.com/milesjdantonio/hokiebikerack/blob/main/frontend/js/api.js"
click node_firmware_model "https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/model/model_api.cpp"
click node_model_ui "https://github.com/milesjdantonio/hokiebikerack/blob/main/frontend/model/app.js"
click node_simulator "https://github.com/milesjdantonio/hokiebikerack/blob/main/tools/device_simulator.py"
click node_rack_api "https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/racks/RackService.java"
click node_device_api "https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/devices/DeviceAuthService.java"
click node_event_api "https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/events/EventService.java"
click node_incident_api "https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/incidents/IncidentService.java"
click node_rider_api "https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/riders/RiderService.java"
click node_reports "https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/reports/ReportService.java"
click node_audit "https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/audit/AuditService.java"

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_rack_hw,node_card_access,node_card_store,node_lock_feedback,node_tamper toneBlue
class node_rack_api,node_device_api,node_event_api,node_incident_api,node_rider_api,node_reports toneAmber
class node_dashboard,node_rider_ui,node_campus_map,node_browser_api toneMint
class node_firmware_model,node_model_ui,node_simulator toneRose
class node_audit,node_database,node_rider,node_staff,node_police toneIndigo
```

## Components

### Rack Firmware

- [Arduino Rack](https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`
- [Card Access](https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/src/card_reader.cpp): `firmware/src/card_reader.cpp`
- [EEPROM Cards](https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/src/card_store.cpp): `firmware/src/card_store.cpp`
- [Lock & Feedback](https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/src/lock.cpp): `firmware/src/lock.cpp`
- [Tamper Detection](https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/lib/hbr_logic/src/tamper_detector.h): `firmware/lib/hbr_logic/src/tamper_detector.h`

### Backend Services

- [Rack Management](https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/racks/RackService.java): `backend/src/main/java/edu/vt/hokiebikerack/racks/RackService.java`
- [Device Authentication](https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/devices/DeviceAuthService.java): `backend/src/main/java/edu/vt/hokiebikerack/devices/DeviceAuthService.java`
- [Event Ingestion](https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/events/EventService.java): `backend/src/main/java/edu/vt/hokiebikerack/events/EventService.java`
- [Incident Workflow](https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/incidents/IncidentService.java): `backend/src/main/java/edu/vt/hokiebikerack/incidents/IncidentService.java`
- [Rider & Cards](https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/riders/RiderService.java): `backend/src/main/java/edu/vt/hokiebikerack/riders/RiderService.java`
- [Reports](https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/reports/ReportService.java): `backend/src/main/java/edu/vt/hokiebikerack/reports/ReportService.java`

### Browser Applications

- [Role Dashboards](https://github.com/milesjdantonio/hokiebikerack/blob/main/frontend/shared/console.js): `frontend/shared/console.js`
- [Rider Interface](https://github.com/milesjdantonio/hokiebikerack/blob/main/frontend/shared/rider.js): `frontend/shared/rider.js`
- [Campus Map](https://github.com/milesjdantonio/hokiebikerack/blob/main/frontend/shared/map.js): `frontend/shared/map.js`
- [Browser API Client](https://github.com/milesjdantonio/hokiebikerack/blob/main/frontend/js/api.js): `frontend/js/api.js`

### Simulation

- [Firmware Model](https://github.com/milesjdantonio/hokiebikerack/blob/main/firmware/model/model_api.cpp): `firmware/model/model_api.cpp`
- [Model Interface](https://github.com/milesjdantonio/hokiebikerack/blob/main/frontend/model/app.js): `frontend/model/app.js`
- [Device Simulator](https://github.com/milesjdantonio/hokiebikerack/blob/main/tools/device_simulator.py): `tools/device_simulator.py`

### Shared Services

- [Audit Log](https://github.com/milesjdantonio/hokiebikerack/blob/main/backend/src/main/java/edu/vt/hokiebikerack/audit/AuditService.java): `backend/src/main/java/edu/vt/hokiebikerack/audit/AuditService.java`
- **PostgreSQL**

### Other components

- **Rider**
- **Staff / Admin**
- **Police**

## Connections

- Rider → Arduino Rack: taps card (evidence: `firmware/src/main.cpp`)
- Arduino Rack → Card Access: polls reader (evidence: `firmware/src/main.cpp`)
- Arduino Rack → EEPROM Cards: checks / enrolls (evidence: `firmware/src/main.cpp`)
- Arduino Rack → Lock & Feedback: controls outputs (evidence: `firmware/src/main.cpp`)
- Arduino Rack → Tamper Detection: checks motion (evidence: `firmware/src/main.cpp`)
- Arduino Rack → Staff / Admin: prints serial events (evidence: `README.md`)
- Staff / Admin → Role Dashboards: uses dashboard (evidence: `README.md`)
- Police → Role Dashboards: uses dashboard (evidence: `README.md`)
- Rider → Rider Interface: uses rider view (evidence: `README.md`)
- Role Dashboards → Browser API Client: calls API client (evidence: `frontend/shared/console.js`)
- Rider Interface → Browser API Client: uses API client
- Role Dashboards → Campus Map: renders map (evidence: `frontend/shared/console.js`)
- Browser API Client → Rack Management: requests backend
- Browser API Client → Event Ingestion: requests backend
- Browser API Client → Rider & Cards: requests backend
- Device Simulator → Device Authentication: simulates rack
- Device Authentication → Event Ingestion: authenticates device (evidence: `backend/src/main/java/edu/vt/hokiebikerack/devices/DeviceAuthService.java`)
- Event Ingestion → Incident Workflow: publishes refusal (evidence: `backend/src/main/java/edu/vt/hokiebikerack/events/EventService.java`)
- Rack Management → Audit Log: records changes (evidence: `backend/src/main/java/edu/vt/hokiebikerack/racks/RackService.java`)
- Event Ingestion → Audit Log: records changes (evidence: `backend/src/main/java/edu/vt/hokiebikerack/events/EventService.java`)
- Incident Workflow → Audit Log: records changes (evidence: `backend/src/main/java/edu/vt/hokiebikerack/incidents/IncidentService.java`)
- Rider & Cards → Audit Log: records changes (evidence: `backend/src/main/java/edu/vt/hokiebikerack/riders/RiderService.java`)
- Rack Management → PostgreSQL: reads / writes (evidence: `backend/src/main/java/edu/vt/hokiebikerack/racks/RackService.java`)
- Event Ingestion → PostgreSQL: reads / writes (evidence: `backend/src/main/java/edu/vt/hokiebikerack/events/EventService.java`)
- Incident Workflow → PostgreSQL: reads / writes (evidence: `backend/src/main/java/edu/vt/hokiebikerack/incidents/IncidentService.java`)
- Rider & Cards → PostgreSQL: reads / writes (evidence: `backend/src/main/java/edu/vt/hokiebikerack/riders/RiderService.java`)
- Reports → PostgreSQL: queries reports (evidence: `backend/src/main/java/edu/vt/hokiebikerack/reports/ReportService.java`)
- Audit Log → PostgreSQL: stores audit entries (evidence: `backend/src/main/java/edu/vt/hokiebikerack/audit/AuditService.java`)
- Model Interface → Firmware Model: boots / steps (evidence: `frontend/model/app.js`)
- Firmware Model → Arduino Rack: runs firmware (evidence: `firmware/model/model_api.cpp`)
