# kelemi90/trash_heatmap architecture

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

- Interactive diagram: https://gitdiagram.com/kelemi90/trash_heatmap
- Repository: https://github.com/kelemi90/trash_heatmap

## Overview

Trash Heatmap records event trash-bin emptying and turns those records into operational views. The main workflow is a worker scanning a bin’s QR code, selecting an approved username, and submitting a timestamped emptying; the server validates the user and enforces a ten-minute per-bin cooldown before storing the record. Dashboards summarize bin locations, recent activity, and usage. Administrators manage users, bin positions, QR labels, and log resets behind session authentication. The README documents capabilities and API behavior; unsampled frontend modules are represented by their tree paths, without asserting undocumented client-to-endpoint calls.

Main entry points: [`server/routes/bins.js`](https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/bins.js) (Bin and analytics API), [`server/server.js`](https://github.com/kelemi90/trash_heatmap/blob/main/server/server.js) (HTTP application), [`server/routes/logs.js`](https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/logs.js) (Emptying logs), [`public/admin.html`](https://github.com/kelemi90/trash_heatmap/blob/main/public/admin.html) (Admin panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_field["Field logging"]
  node_binpage["Bin logging page<br/>[bin.html]"]
  node_logapi["Emptying logs<br/>[logs.js]"]
  node_qrlabels["QR label API<br/>[qrLabels.js]"]
  node_qrpage["QR label manager<br/>[qr_labels.html]"]
end

subgraph group_insights["Usage insights"]
  node_dashboard["Dashboard<br/>[dashboard.html]"]
  node_dashjs["Dashboard views<br/>[dashboard.js]"]
  node_heatmap["Heatmap view<br/>[heatmap.html]"]
  node_mapjs["Bin map<br/>[map.js]"]
  node_report["Reports<br/>[report.html]"]
  node_reportjs["Report analysis<br/>[report.js]"]
  node_timesjs["Bin timing view<br/>[bin_times.js]"]
  node_ranking["Bin ranking<br/>[ranking.html]"]
end

subgraph group_admin["Administration"]
  node_adminui["Admin panel<br/>[admin.html]"]
  node_bineditor["Bin editor<br/>[bin_editor.html]"]
  node_usersapi["User management<br/>[users.js]"]
  node_binapi["Bin and analytics API<br/>[bins.js]"]
  node_authapi["Admin authentication<br/>[auth.js]"]
  node_guard["Admin access guard<br/>[adminAuth.js]"]
end

subgraph group_platform["Server and data"]
  node_server["HTTP application<br/>[server.js]"]
  node_db[("SQLite records<br/>[trash.db]")]
  node_session[("Redis sessions")]
  node_logger["Server logger<br/>[logger.js]"]
end

node_worker(("Worker"))
node_adminactor(("Administrator"))

node_worker -->|"scans QR"| node_binpage
node_binpage -->|"submits emptying"| node_logapi
node_logapi -->|"validates and records"| node_db
node_qrpage -->|"requests labels"| node_qrlabels
node_qrlabels -->|"encodes bin URL"| node_binpage
node_adminactor -->|"manages system"| node_adminui
node_adminui -->|"signs in"| node_authapi
node_authapi -->|"stores session"| node_session
node_adminui -->|"manages users"| node_usersapi
node_usersapi -->|"reads and writes users"| node_db
node_adminui -->|"edits positions"| node_bineditor
node_bineditor -->|"updates bins"| node_binapi
node_binapi -->|"reads and updates"| node_db
node_adminui -->|"reviews and resets logs"| node_logapi
node_logapi -->|"protects reset"| node_guard
node_binapi -->|"protects position changes"| node_guard
node_dashboard -->|"renders views"| node_dashjs
node_dashjs -->|"loads status and heatmap"| node_binapi
node_heatmap -->|"loads usage counts"| node_binapi
node_mapjs -->|"loads bin locations"| node_binapi
node_report -->|"renders reports"| node_reportjs
node_reportjs -->|"loads activity data"| node_logapi
node_timesjs -->|"loads bin status"| node_binapi
node_ranking -->|"loads usage ranking"| node_logapi
node_server -->|"mounts routes"| node_authapi
node_server -->|"mounts routes"| node_binapi
node_server -->|"mounts routes"| node_logapi
node_server -->|"mounts routes"| node_usersapi
node_server -->|"mounts routes"| node_qrlabels
node_server -->|"guards admin pages"| node_guard
node_server -->|"writes request errors"| node_logger

click node_binpage "https://github.com/kelemi90/trash_heatmap/blob/main/public/bin.html"
click node_logapi "https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/logs.js"
click node_qrlabels "https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/qrLabels.js"
click node_qrpage "https://github.com/kelemi90/trash_heatmap/blob/main/public/qr_labels.html"
click node_dashboard "https://github.com/kelemi90/trash_heatmap/blob/main/public/dashboard.html"
click node_dashjs "https://github.com/kelemi90/trash_heatmap/blob/main/public/js/dashboard.js"
click node_heatmap "https://github.com/kelemi90/trash_heatmap/blob/main/public/heatmap.html"
click node_mapjs "https://github.com/kelemi90/trash_heatmap/blob/main/public/js/map.js"
click node_report "https://github.com/kelemi90/trash_heatmap/blob/main/public/report.html"
click node_reportjs "https://github.com/kelemi90/trash_heatmap/blob/main/public/js/report.js"
click node_timesjs "https://github.com/kelemi90/trash_heatmap/blob/main/public/js/bin_times.js"
click node_ranking "https://github.com/kelemi90/trash_heatmap/blob/main/public/ranking.html"
click node_adminui "https://github.com/kelemi90/trash_heatmap/blob/main/public/admin.html"
click node_bineditor "https://github.com/kelemi90/trash_heatmap/blob/main/public/bin_editor.html"
click node_usersapi "https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/users.js"
click node_binapi "https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/bins.js"
click node_authapi "https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/auth.js"
click node_guard "https://github.com/kelemi90/trash_heatmap/blob/main/server/middleware/adminAuth.js"
click node_server "https://github.com/kelemi90/trash_heatmap/blob/main/server/server.js"
click node_db "https://github.com/kelemi90/trash_heatmap/blob/main/database/trash.db"
click node_logger "https://github.com/kelemi90/trash_heatmap/blob/main/server/logger.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_binpage,node_logapi,node_qrlabels,node_qrpage toneBlue
class node_dashboard,node_dashjs,node_heatmap,node_mapjs,node_report,node_reportjs,node_timesjs,node_ranking toneAmber
class node_adminui,node_bineditor,node_usersapi,node_binapi,node_authapi,node_guard toneMint
class node_server,node_db,node_session,node_logger,node_worker toneRose
class node_adminactor toneIndigo
```

## Components

### Field logging

- [Bin logging page](https://github.com/kelemi90/trash_heatmap/blob/main/public/bin.html): `public/bin.html`
- [Emptying logs](https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/logs.js): `server/routes/logs.js`
- [QR label API](https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/qrLabels.js): `server/routes/qrLabels.js`
- [QR label manager](https://github.com/kelemi90/trash_heatmap/blob/main/public/qr_labels.html): `public/qr_labels.html`

### Usage insights

- [Dashboard](https://github.com/kelemi90/trash_heatmap/blob/main/public/dashboard.html): `public/dashboard.html`
- [Dashboard views](https://github.com/kelemi90/trash_heatmap/blob/main/public/js/dashboard.js): `public/js/dashboard.js`
- [Heatmap view](https://github.com/kelemi90/trash_heatmap/blob/main/public/heatmap.html): `public/heatmap.html`
- [Bin map](https://github.com/kelemi90/trash_heatmap/blob/main/public/js/map.js): `public/js/map.js`
- [Reports](https://github.com/kelemi90/trash_heatmap/blob/main/public/report.html): `public/report.html`
- [Report analysis](https://github.com/kelemi90/trash_heatmap/blob/main/public/js/report.js): `public/js/report.js`
- [Bin timing view](https://github.com/kelemi90/trash_heatmap/blob/main/public/js/bin_times.js): `public/js/bin_times.js`
- [Bin ranking](https://github.com/kelemi90/trash_heatmap/blob/main/public/ranking.html): `public/ranking.html`

### Administration

- [Admin panel](https://github.com/kelemi90/trash_heatmap/blob/main/public/admin.html): `public/admin.html`
- [Bin editor](https://github.com/kelemi90/trash_heatmap/blob/main/public/bin_editor.html): `public/bin_editor.html`
- [User management](https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/users.js): `server/routes/users.js`
- [Bin and analytics API](https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/bins.js): `server/routes/bins.js`
- [Admin authentication](https://github.com/kelemi90/trash_heatmap/blob/main/server/routes/auth.js): `server/routes/auth.js`
- [Admin access guard](https://github.com/kelemi90/trash_heatmap/blob/main/server/middleware/adminAuth.js): `server/middleware/adminAuth.js`

### Server and data

- [HTTP application](https://github.com/kelemi90/trash_heatmap/blob/main/server/server.js): `server/server.js`
- [SQLite records](https://github.com/kelemi90/trash_heatmap/blob/main/database/trash.db): `database/trash.db`
- **Redis sessions**
- [Server logger](https://github.com/kelemi90/trash_heatmap/blob/main/server/logger.js): `server/logger.js`

### Other components

- **Worker**
- **Administrator**

## Connections

- Worker → Bin logging page: scans QR (evidence: `README.md`)
- Bin logging page → Emptying logs: submits emptying (evidence: `README.md`)
- Emptying logs → SQLite records: validates and records (evidence: `server/routes/logs.js`)
- QR label manager → QR label API: requests labels (evidence: `README.md`)
- QR label API → Bin logging page: encodes bin URL (evidence: `server/routes/qrLabels.js`)
- Administrator → Admin panel: manages system (evidence: `README.md`)
- Admin panel → Admin authentication: signs in (evidence: `README.md`)
- Admin authentication → Redis sessions: stores session
- Admin panel → User management: manages users (evidence: `README.md`)
- User management → SQLite records: reads and writes users (evidence: `server/routes/users.js`)
- Admin panel → Bin editor: edits positions (evidence: `README.md`)
- Bin editor → Bin and analytics API: updates bins (evidence: `README.md`)
- Bin and analytics API → SQLite records: reads and updates (evidence: `server/routes/bins.js`)
- Admin panel → Emptying logs: reviews and resets logs (evidence: `README.md`)
- Emptying logs → Admin access guard: protects reset (evidence: `server/routes/logs.js`)
- Bin and analytics API → Admin access guard: protects position changes (evidence: `server/routes/bins.js`)
- Dashboard → Dashboard views: renders views (evidence: `README.md`)
- Dashboard views → Bin and analytics API: loads status and heatmap (evidence: `README.md`)
- Heatmap view → Bin and analytics API: loads usage counts (evidence: `README.md`)
- Bin map → Bin and analytics API: loads bin locations (evidence: `README.md`)
- Reports → Report analysis: renders reports (evidence: `README.md`)
- Report analysis → Emptying logs: loads activity data (evidence: `README.md`)
- Bin timing view → Bin and analytics API: loads bin status (evidence: `README.md`)
- Bin ranking → Emptying logs: loads usage ranking (evidence: `README.md`)
- HTTP application → Admin authentication: mounts routes (evidence: `server/server.js`)
- HTTP application → Bin and analytics API: mounts routes (evidence: `server/server.js`)
- HTTP application → Emptying logs: mounts routes (evidence: `server/server.js`)
- HTTP application → User management: mounts routes (evidence: `server/server.js`)
- HTTP application → QR label API: mounts routes (evidence: `server/server.js`)
- HTTP application → Admin access guard: guards admin pages (evidence: `server/server.js`)
- HTTP application → Server logger: writes request errors (evidence: `server/server.js`)
