# digbatt/cits3200 architecture

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

- Interactive diagram: https://gitdiagram.com/digbatt/cits3200
- Repository: https://github.com/digbatt/cits3200

## Overview

nUWAy Fleet Dashboard combines a Flask service and browser dashboard for viewing shuttle positions, history, fleet utilisation and operational status; it also supports rider pickup requests and authenticated operator actions. The documented live-data workflow polls REV vehicle endpoints and appends snapshots for later viewing. The source excerpts establish app registration and several backend dependencies; frontend-to-API wiring and logger internals were not sampled, so those links are omitted or marked unverified.

Main entry points: [`backend/app.py`](https://github.com/digbatt/cits3200/blob/main/backend/app.py) (Flask app), [`frontend/js/main.js`](https://github.com/digbatt/cits3200/blob/main/frontend/js/main.js) (Dashboard shell), [`backend/api/pickup_requests.py`](https://github.com/digbatt/cits3200/blob/main/backend/api/pickup_requests.py) (Pickup API), [`backend/repository/base.py`](https://github.com/digbatt/cits3200/blob/main/backend/repository/base.py) (Repository interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Service runtime"]
  node_app["Flask app<br/>[app.py]"]
  node_config["App configuration<br/>[config.py]"]
  node_auth["Admin sign-in<br/>[auth.py]"]
  node_api_positions["Position API<br/>[positions.py]"]
  node_api_vehicles["Vehicle API<br/>[vehicles.py]"]
  node_api_metrics["Metrics API<br/>[metrics.py]"]
  node_api_earth["Earth view API<br/>[earth.py]"]
  node_api_params["Query parsing<br/>[params.py]"]
end

subgraph group_telemetry["Fleet telemetry"]
  node_tum["Utilisation model<br/>[tum.py]"]
  node_models["Fleet data models<br/>[models.py]"]
  node_repository["Repository interface<br/>[base.py]"]
  node_csv_store[("CSV position store<br/>[csv_repo.py]")]
  node_logger["Live-data logger<br/>[logger.py]"]
end

subgraph group_operations["Rider and operator"]
  node_api_downtime["Downtime API<br/>[downtime.py]"]
  node_api_pickups["Pickup API<br/>[pickup_requests.py]"]
  node_pickup_store["Pickup requests<br/>[pickup_requests.py]"]
  node_stops["Stops and routes<br/>[stops.py]"]
  node_downtime_store["Downtime records<br/>[downtime.py]"]
end

subgraph group_dashboard["Browser dashboard"]
  node_frontend["Dashboard shell<br/>[main.js]"]
  node_bus_model["Bus visual model<br/>[bus-model.js]"]
  node_map3d["3D map views<br/>[view3d.js]"]
  node_campus3d["Campus 3D view<br/>[campus3d.js]"]
  node_earth3d["Earth 3D view<br/>[earth3d.js]"]
  node_timeline["Fleet timeline<br/>[timeline.js]"]
  node_utilisation["Utilisation view<br/>[utilisation.js]"]
  node_operator_view["Operator view<br/>[operator.js]"]
  node_admin_view["Admin dashboard<br/>[admin.js]"]
  node_rider_view["Rider interface<br/>[rider.js]"]
end

node_fleet_user(("Fleet user"))
node_operator(("Operator"))
node_rider(("Rider"))
node_rev["REV tracking"]

node_fleet_user -.->|"views fleet"| node_frontend
node_operator -.->|"manages service"| node_operator_view
node_rider -.->|"requests pickup"| node_rider_view
node_app -->|"loads settings"| node_config
node_app -->|"registers sign-in"| node_auth
node_app -->|"registers routes"| node_api_positions
node_app -->|"registers routes"| node_api_vehicles
node_app -->|"registers routes"| node_api_metrics
node_app -->|"registers routes"| node_api_earth
node_app -->|"registers routes"| node_api_downtime
node_app -->|"registers routes"| node_api_pickups
node_app -->|"configures repository"| node_repository
node_api_positions -->|"parses filters"| node_api_params
node_api_metrics -->|"parses filters"| node_api_params
node_api_metrics -->|"calculates metrics"| node_tum
node_api_pickups -->|"manages requests"| node_pickup_store
node_api_pickups -->|"validates routes"| node_stops
node_api_downtime -->|"manages records"| node_downtime_store
node_downtime_store -->|"uses error type"| node_repository
node_repository -->|"stores positions"| node_models
node_csv_store -->|"implements interface"| node_repository
node_tum -->|"classifies samples"| node_models
node_config -->|"loads network"| node_stops
node_logger -.->|"polls snapshots"| node_rev
node_logger -.->|"appends snapshots"| node_csv_store
node_map3d -->|"uses model"| node_bus_model
node_campus3d -->|"uses model"| node_bus_model
node_earth3d -->|"uses model"| node_bus_model
node_frontend -.->|"dashboard feature"| node_timeline
node_frontend -.->|"dashboard feature"| node_utilisation
node_frontend -.->|"dashboard feature"| node_map3d
node_operator_view -.->|"uses operations API"| node_api_downtime
node_rider_view -.->|"uses pickup API"| node_api_pickups

click node_app "https://github.com/digbatt/cits3200/blob/main/backend/app.py"
click node_config "https://github.com/digbatt/cits3200/blob/main/backend/config.py"
click node_auth "https://github.com/digbatt/cits3200/blob/main/backend/auth.py"
click node_api_positions "https://github.com/digbatt/cits3200/blob/main/backend/api/positions.py"
click node_api_vehicles "https://github.com/digbatt/cits3200/blob/main/backend/api/vehicles.py"
click node_api_metrics "https://github.com/digbatt/cits3200/blob/main/backend/api/metrics.py"
click node_api_earth "https://github.com/digbatt/cits3200/blob/main/backend/api/earth.py"
click node_api_params "https://github.com/digbatt/cits3200/blob/main/backend/api/params.py"
click node_api_downtime "https://github.com/digbatt/cits3200/blob/main/backend/api/downtime.py"
click node_api_pickups "https://github.com/digbatt/cits3200/blob/main/backend/api/pickup_requests.py"
click node_pickup_store "https://github.com/digbatt/cits3200/blob/main/backend/pickup_requests.py"
click node_stops "https://github.com/digbatt/cits3200/blob/main/backend/stops.py"
click node_downtime_store "https://github.com/digbatt/cits3200/blob/main/backend/downtime.py"
click node_tum "https://github.com/digbatt/cits3200/blob/main/backend/metrics/tum.py"
click node_models "https://github.com/digbatt/cits3200/blob/main/backend/models.py"
click node_repository "https://github.com/digbatt/cits3200/blob/main/backend/repository/base.py"
click node_csv_store "https://github.com/digbatt/cits3200/blob/main/backend/repository/csv_repo.py"
click node_logger "https://github.com/digbatt/cits3200/blob/main/backend/logger.py"
click node_frontend "https://github.com/digbatt/cits3200/blob/main/frontend/js/main.js"
click node_bus_model "https://github.com/digbatt/cits3200/blob/main/frontend/js/bus-model.js"
click node_map3d "https://github.com/digbatt/cits3200/blob/main/frontend/js/view3d.js"
click node_campus3d "https://github.com/digbatt/cits3200/blob/main/frontend/js/campus3d.js"
click node_earth3d "https://github.com/digbatt/cits3200/blob/main/frontend/js/earth3d.js"
click node_timeline "https://github.com/digbatt/cits3200/blob/main/frontend/js/timeline.js"
click node_utilisation "https://github.com/digbatt/cits3200/blob/main/frontend/js/utilisation.js"
click node_operator_view "https://github.com/digbatt/cits3200/blob/main/frontend/js/operator.js"
click node_admin_view "https://github.com/digbatt/cits3200/blob/main/frontend/js/admin.js"
click node_rider_view "https://github.com/digbatt/cits3200/blob/main/frontend/js/rider.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_app,node_config,node_auth,node_api_positions,node_api_vehicles,node_api_metrics,node_api_earth,node_api_params,node_fleet_user toneBlue
class node_tum,node_models,node_repository,node_csv_store,node_logger toneAmber
class node_api_downtime,node_api_pickups,node_pickup_store,node_stops,node_downtime_store toneMint
class node_frontend,node_bus_model,node_map3d,node_campus3d,node_earth3d,node_timeline,node_utilisation,node_operator_view,node_admin_view,node_rider_view toneRose
class node_operator,node_rider,node_rev toneIndigo
```

## Components

### Service runtime

- [Flask app](https://github.com/digbatt/cits3200/blob/main/backend/app.py): `backend/app.py`
- [App configuration](https://github.com/digbatt/cits3200/blob/main/backend/config.py): `backend/config.py`
- [Admin sign-in](https://github.com/digbatt/cits3200/blob/main/backend/auth.py): `backend/auth.py`
- [Position API](https://github.com/digbatt/cits3200/blob/main/backend/api/positions.py): `backend/api/positions.py`
- [Vehicle API](https://github.com/digbatt/cits3200/blob/main/backend/api/vehicles.py): `backend/api/vehicles.py`
- [Metrics API](https://github.com/digbatt/cits3200/blob/main/backend/api/metrics.py): `backend/api/metrics.py`
- [Earth view API](https://github.com/digbatt/cits3200/blob/main/backend/api/earth.py): `backend/api/earth.py`
- [Query parsing](https://github.com/digbatt/cits3200/blob/main/backend/api/params.py): `backend/api/params.py`

### Fleet telemetry

- [Utilisation model](https://github.com/digbatt/cits3200/blob/main/backend/metrics/tum.py): `backend/metrics/tum.py`
- [Fleet data models](https://github.com/digbatt/cits3200/blob/main/backend/models.py): `backend/models.py`
- [Repository interface](https://github.com/digbatt/cits3200/blob/main/backend/repository/base.py): `backend/repository/base.py`
- [CSV position store](https://github.com/digbatt/cits3200/blob/main/backend/repository/csv_repo.py): `backend/repository/csv_repo.py`
- [Live-data logger](https://github.com/digbatt/cits3200/blob/main/backend/logger.py): `backend/logger.py`

### Rider and operator

- [Downtime API](https://github.com/digbatt/cits3200/blob/main/backend/api/downtime.py): `backend/api/downtime.py`
- [Pickup API](https://github.com/digbatt/cits3200/blob/main/backend/api/pickup_requests.py): `backend/api/pickup_requests.py`
- [Pickup requests](https://github.com/digbatt/cits3200/blob/main/backend/pickup_requests.py): `backend/pickup_requests.py`
- [Stops and routes](https://github.com/digbatt/cits3200/blob/main/backend/stops.py): `backend/stops.py`
- [Downtime records](https://github.com/digbatt/cits3200/blob/main/backend/downtime.py): `backend/downtime.py`

### Browser dashboard

- [Dashboard shell](https://github.com/digbatt/cits3200/blob/main/frontend/js/main.js): `frontend/js/main.js`
- [Bus visual model](https://github.com/digbatt/cits3200/blob/main/frontend/js/bus-model.js): `frontend/js/bus-model.js`
- [3D map views](https://github.com/digbatt/cits3200/blob/main/frontend/js/view3d.js): `frontend/js/view3d.js`
- [Campus 3D view](https://github.com/digbatt/cits3200/blob/main/frontend/js/campus3d.js): `frontend/js/campus3d.js`
- [Earth 3D view](https://github.com/digbatt/cits3200/blob/main/frontend/js/earth3d.js): `frontend/js/earth3d.js`
- [Fleet timeline](https://github.com/digbatt/cits3200/blob/main/frontend/js/timeline.js): `frontend/js/timeline.js`
- [Utilisation view](https://github.com/digbatt/cits3200/blob/main/frontend/js/utilisation.js): `frontend/js/utilisation.js`
- [Operator view](https://github.com/digbatt/cits3200/blob/main/frontend/js/operator.js): `frontend/js/operator.js`
- [Admin dashboard](https://github.com/digbatt/cits3200/blob/main/frontend/js/admin.js): `frontend/js/admin.js`
- [Rider interface](https://github.com/digbatt/cits3200/blob/main/frontend/js/rider.js): `frontend/js/rider.js`

### Other components

- **Fleet user**
- **Operator**
- **Rider**
- **REV tracking**

## Connections

- Fleet user → Dashboard shell: views fleet (evidence: `README.md`)
- Operator → Operator view: manages service (evidence: `README.md`)
- Rider → Rider interface: requests pickup (evidence: `README.md`)
- Flask app → App configuration: loads settings (evidence: `backend/app.py`)
- Flask app → Admin sign-in: registers sign-in (evidence: `backend/app.py`)
- Flask app → Position API: registers routes (evidence: `backend/app.py`)
- Flask app → Vehicle API: registers routes (evidence: `backend/app.py`)
- Flask app → Metrics API: registers routes (evidence: `backend/app.py`)
- Flask app → Earth view API: registers routes (evidence: `backend/app.py`)
- Flask app → Downtime API: registers routes (evidence: `backend/app.py`)
- Flask app → Pickup API: registers routes (evidence: `backend/app.py`)
- Flask app → Repository interface: configures repository (evidence: `backend/app.py`)
- Position API → Query parsing: parses filters (evidence: `backend/api/positions.py`)
- Metrics API → Query parsing: parses filters (evidence: `backend/api/metrics.py`)
- Metrics API → Utilisation model: calculates metrics (evidence: `backend/api/metrics.py`)
- Pickup API → Pickup requests: manages requests (evidence: `backend/api/pickup_requests.py`)
- Pickup API → Stops and routes: validates routes (evidence: `backend/api/pickup_requests.py`)
- Downtime API → Downtime records: manages records (evidence: `backend/api/downtime.py`)
- Downtime records → Repository interface: uses error type (evidence: `backend/downtime.py`)
- Repository interface → Fleet data models: stores positions (evidence: `backend/repository/base.py`)
- CSV position store → Repository interface: implements interface (evidence: `backend/repository/csv_repo.py`)
- Utilisation model → Fleet data models: classifies samples (evidence: `backend/metrics/tum.py`)
- App configuration → Stops and routes: loads network (evidence: `backend/config.py`)
- Live-data logger → REV tracking: polls snapshots (evidence: `README.md`)
- Live-data logger → CSV position store: appends snapshots (evidence: `README.md`)
- 3D map views → Bus visual model: uses model (evidence: `frontend/js/view3d.js`)
- Campus 3D view → Bus visual model: uses model (evidence: `frontend/js/campus3d.js`)
- Earth 3D view → Bus visual model: uses model (evidence: `frontend/js/earth3d.js`)
- Dashboard shell → Fleet timeline: dashboard feature
- Dashboard shell → Utilisation view: dashboard feature
- Dashboard shell → 3D map views: dashboard feature
- Operator view → Downtime API: uses operations API
- Rider interface → Pickup API: uses pickup API
