# omkarchavan415/cleantrack architecture

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

- Interactive diagram: https://gitdiagram.com/omkarchavan415/cleantrack
- Repository: https://github.com/omkarchavan415/cleantrack

## Overview

This is a garbage-truck tracking application for administrators, drivers, and residents. A driver authenticates, joins their authorized truck channel, and streams GPS fixes; the server records positions, broadcasts map updates, and checks household geofences to send cooldown-limited resident alerts. Admin capabilities include managing drivers, trucks, and households and reviewing truck history and household alerts. The graph reflects the server and API flow shown in excerpts; frontend behavior is not sampled, so only static serving is shown. Also, the README supplied no capability documentation.

Main entry points: [`backend/server.js`](https://github.com/omkarchavan415/cleantrack/blob/main/backend/server.js) (Application server), [`backend/db/repo.js`](https://github.com/omkarchavan415/cleantrack/blob/main/backend/db/repo.js) (Data repository), [`backend/routes/auth.js`](https://github.com/omkarchavan415/cleantrack/blob/main/backend/routes/auth.js) (Authentication API), [`backend/routes/households.js`](https://github.com/omkarchavan415/cleantrack/blob/main/backend/routes/households.js) (Household API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_auth_routes["Authentication API<br/>[auth.js]"]
  node_household_routes["Household API<br/>[households.js]"]
  node_truck_routes["Truck API<br/>[trucks.js]"]
  node_auth_middleware["Role authorization<br/>[auth.js]"]
  node_jwt["JWT tokens<br/>[jwt.js]"]
  node_async_wrapper["Async route wrapper<br/>[wrapasync.js]"]
end

subgraph group_realtime["Live tracking"]
  node_server["Application server<br/>[server.js]"]
end

subgraph group_domain["Geofences and alerts"]
  node_geofence["Geofence evaluation<br/>[geofenceEngine.js]"]
  node_geo["Distance calculation<br/>[geo.js]"]
end

subgraph group_storage["Persistence"]
  node_repo["Data repository<br/>[repo.js]"]
  node_db_connection["Mongo connection<br/>[index.js]"]
  node_mongo[("MongoDB")]
  node_truck_model["Truck records<br/>[Truck.js]"]
  node_position_model["Position history<br/>[TruckPosition.js]"]
  node_household_model["Household records<br/>[Household.js]"]
  node_alert_model["Alert records<br/>[Alert.js]"]
  node_user_model["User records<br/>[User.js]"]
end

subgraph group_clients["Web clients"]
  node_admin_ui["Admin interface<br/>[admin.html]"]
  node_driver_ui["Driver interface<br/>[driver.html]"]
  node_resident_ui["Resident interface<br/>[resident.html]"]
  node_public_ui["Public map interface<br/>[index.html]"]
end

node_admin(("Administrator"))
node_driver(("Driver"))
node_resident(("Resident"))

node_server -->|"mounts routes"| node_auth_routes
node_server -->|"mounts routes"| node_household_routes
node_server -->|"mounts routes"| node_truck_routes
node_server -->|"connects database"| node_db_connection
node_server -->|"sweeps offline"| node_repo
node_server -->|"records positions"| node_repo
node_server -->|"checks geofences"| node_geofence
node_server -->|"verifies socket token"| node_jwt
node_server -->|"serves static files"| node_admin_ui
node_server -->|"serves static files"| node_driver_ui
node_server -->|"serves static files"| node_resident_ui
node_server -->|"serves static files"| node_public_ui
node_auth_routes -->|"looks up users"| node_user_model
node_auth_routes -->|"registers trucks"| node_repo
node_auth_routes -->|"signs tokens"| node_jwt
node_auth_routes -->|"protects routes"| node_auth_middleware
node_auth_routes -->|"wraps handlers"| node_async_wrapper
node_household_routes -->|"manages households"| node_repo
node_household_routes -->|"protects routes"| node_auth_middleware
node_household_routes -->|"wraps handlers"| node_async_wrapper
node_truck_routes -->|"reads truck data"| node_repo
node_truck_routes -->|"protects routes"| node_auth_middleware
node_truck_routes -->|"wraps handlers"| node_async_wrapper
node_auth_middleware -->|"verifies tokens"| node_jwt
node_geofence -->|"loads and records alerts"| node_repo
node_geofence -->|"measures distance"| node_geo
node_repo -->|"queries and updates"| node_truck_model
node_repo -->|"stores history"| node_position_model
node_repo -->|"queries households"| node_household_model
node_repo -->|"stores alert records"| node_alert_model
node_db_connection -->|"connects"| node_mongo

click node_server "https://github.com/omkarchavan415/cleantrack/blob/main/backend/server.js"
click node_auth_routes "https://github.com/omkarchavan415/cleantrack/blob/main/backend/routes/auth.js"
click node_household_routes "https://github.com/omkarchavan415/cleantrack/blob/main/backend/routes/households.js"
click node_truck_routes "https://github.com/omkarchavan415/cleantrack/blob/main/backend/routes/trucks.js"
click node_auth_middleware "https://github.com/omkarchavan415/cleantrack/blob/main/backend/middleware/auth.js"
click node_jwt "https://github.com/omkarchavan415/cleantrack/blob/main/backend/utils/jwt.js"
click node_async_wrapper "https://github.com/omkarchavan415/cleantrack/blob/main/backend/utils/wrapasync.js"
click node_geofence "https://github.com/omkarchavan415/cleantrack/blob/main/backend/geofenceEngine.js"
click node_geo "https://github.com/omkarchavan415/cleantrack/blob/main/backend/utils/geo.js"
click node_repo "https://github.com/omkarchavan415/cleantrack/blob/main/backend/db/repo.js"
click node_db_connection "https://github.com/omkarchavan415/cleantrack/blob/main/backend/db/index.js"
click node_truck_model "https://github.com/omkarchavan415/cleantrack/blob/main/backend/models/Truck.js"
click node_position_model "https://github.com/omkarchavan415/cleantrack/blob/main/backend/models/TruckPosition.js"
click node_household_model "https://github.com/omkarchavan415/cleantrack/blob/main/backend/models/Household.js"
click node_alert_model "https://github.com/omkarchavan415/cleantrack/blob/main/backend/models/Alert.js"
click node_user_model "https://github.com/omkarchavan415/cleantrack/blob/main/backend/models/User.js"
click node_admin_ui "https://github.com/omkarchavan415/cleantrack/blob/main/backend/public/admin.html"
click node_driver_ui "https://github.com/omkarchavan415/cleantrack/blob/main/backend/public/driver.html"
click node_resident_ui "https://github.com/omkarchavan415/cleantrack/blob/main/backend/public/resident.html"
click node_public_ui "https://github.com/omkarchavan415/cleantrack/blob/main/backend/public/index.html"

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_auth_routes,node_household_routes,node_truck_routes,node_auth_middleware,node_jwt,node_async_wrapper toneBlue
class node_server toneAmber
class node_geofence,node_geo toneMint
class node_repo,node_db_connection,node_mongo,node_truck_model,node_position_model,node_household_model,node_alert_model,node_user_model toneRose
class node_admin_ui,node_driver_ui,node_resident_ui,node_public_ui,node_admin,node_driver,node_resident toneIndigo
```

## Components

### API and access

- [Authentication API](https://github.com/omkarchavan415/cleantrack/blob/main/backend/routes/auth.js): `backend/routes/auth.js`
- [Household API](https://github.com/omkarchavan415/cleantrack/blob/main/backend/routes/households.js): `backend/routes/households.js`
- [Truck API](https://github.com/omkarchavan415/cleantrack/blob/main/backend/routes/trucks.js): `backend/routes/trucks.js`
- [Role authorization](https://github.com/omkarchavan415/cleantrack/blob/main/backend/middleware/auth.js): `backend/middleware/auth.js`
- [JWT tokens](https://github.com/omkarchavan415/cleantrack/blob/main/backend/utils/jwt.js): `backend/utils/jwt.js`
- [Async route wrapper](https://github.com/omkarchavan415/cleantrack/blob/main/backend/utils/wrapasync.js): `backend/utils/wrapasync.js`

### Live tracking

- [Application server](https://github.com/omkarchavan415/cleantrack/blob/main/backend/server.js): `backend/server.js`

### Geofences and alerts

- [Geofence evaluation](https://github.com/omkarchavan415/cleantrack/blob/main/backend/geofenceEngine.js): `backend/geofenceEngine.js`
- [Distance calculation](https://github.com/omkarchavan415/cleantrack/blob/main/backend/utils/geo.js): `backend/utils/geo.js`

### Persistence

- [Data repository](https://github.com/omkarchavan415/cleantrack/blob/main/backend/db/repo.js): `backend/db/repo.js`
- [Mongo connection](https://github.com/omkarchavan415/cleantrack/blob/main/backend/db/index.js): `backend/db/index.js`
- **MongoDB**
- [Truck records](https://github.com/omkarchavan415/cleantrack/blob/main/backend/models/Truck.js): `backend/models/Truck.js`
- [Position history](https://github.com/omkarchavan415/cleantrack/blob/main/backend/models/TruckPosition.js): `backend/models/TruckPosition.js`
- [Household records](https://github.com/omkarchavan415/cleantrack/blob/main/backend/models/Household.js): `backend/models/Household.js`
- [Alert records](https://github.com/omkarchavan415/cleantrack/blob/main/backend/models/Alert.js): `backend/models/Alert.js`
- [User records](https://github.com/omkarchavan415/cleantrack/blob/main/backend/models/User.js): `backend/models/User.js`

### Web clients

- [Admin interface](https://github.com/omkarchavan415/cleantrack/blob/main/backend/public/admin.html): `backend/public/admin.html`
- [Driver interface](https://github.com/omkarchavan415/cleantrack/blob/main/backend/public/driver.html): `backend/public/driver.html`
- [Resident interface](https://github.com/omkarchavan415/cleantrack/blob/main/backend/public/resident.html): `backend/public/resident.html`
- [Public map interface](https://github.com/omkarchavan415/cleantrack/blob/main/backend/public/index.html): `backend/public/index.html`

### Other components

- **Administrator**
- **Driver**
- **Resident**

## Connections

- Application server → Authentication API: mounts routes (evidence: `backend/server.js`)
- Application server → Household API: mounts routes (evidence: `backend/server.js`)
- Application server → Truck API: mounts routes (evidence: `backend/server.js`)
- Application server → Mongo connection: connects database (evidence: `backend/server.js`)
- Application server → Data repository: sweeps offline (evidence: `backend/server.js`)
- Application server → Data repository: records positions (evidence: `backend/server.js`)
- Application server → Geofence evaluation: checks geofences (evidence: `backend/server.js`)
- Application server → JWT tokens: verifies socket token (evidence: `backend/server.js`)
- Application server → Admin interface: serves static files (evidence: `backend/server.js`)
- Application server → Driver interface: serves static files (evidence: `backend/server.js`)
- Application server → Resident interface: serves static files (evidence: `backend/server.js`)
- Application server → Public map interface: serves static files (evidence: `backend/server.js`)
- Authentication API → User records: looks up users (evidence: `backend/routes/auth.js`)
- Authentication API → Data repository: registers trucks (evidence: `backend/routes/auth.js`)
- Authentication API → JWT tokens: signs tokens (evidence: `backend/routes/auth.js`)
- Authentication API → Role authorization: protects routes (evidence: `backend/routes/auth.js`)
- Authentication API → Async route wrapper: wraps handlers (evidence: `backend/routes/auth.js`)
- Household API → Data repository: manages households (evidence: `backend/routes/households.js`)
- Household API → Role authorization: protects routes (evidence: `backend/routes/households.js`)
- Household API → Async route wrapper: wraps handlers (evidence: `backend/routes/households.js`)
- Truck API → Data repository: reads truck data (evidence: `backend/routes/trucks.js`)
- Truck API → Role authorization: protects routes (evidence: `backend/routes/trucks.js`)
- Truck API → Async route wrapper: wraps handlers (evidence: `backend/routes/trucks.js`)
- Role authorization → JWT tokens: verifies tokens (evidence: `backend/middleware/auth.js`)
- Geofence evaluation → Data repository: loads and records alerts (evidence: `backend/geofenceEngine.js`)
- Geofence evaluation → Distance calculation: measures distance (evidence: `backend/geofenceEngine.js`)
- Data repository → Truck records: queries and updates (evidence: `backend/db/repo.js`)
- Data repository → Position history: stores history (evidence: `backend/db/repo.js`)
- Data repository → Household records: queries households (evidence: `backend/db/repo.js`)
- Data repository → Alert records: stores alert records (evidence: `backend/db/repo.js`)
- Mongo connection → MongoDB: connects (evidence: `backend/db/index.js`)