# dwarffyz/key_borrowing_system architecture

> Architecture diagram of the GitHub repository dwarffyz/key_borrowing_system, 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/dwarffyz/key_borrowing_system
- Repository: https://github.com/dwarffyz/key_borrowing_system

## Overview

Key Borrowing System is a web application for campus key borrowing, administration, and optional ESP32-controlled lockers. Users authenticate, scan a QR code, and record a borrow or return; administrators manage keys and lockers, users, QR codes, reports, announcements, and system activity. The Express server coordinates the web API and MongoDB models, while the ESP32 firmware provides a separate locker-control and captive-portal path. The README documents these capabilities, but the server and browser excerpts are partial, so some feature-level connections are documented rather than traced through individual routes.

Main entry points: [`public/server/server.js`](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/server.js) (API server), [`public/html`](https://github.com/dwarffyz/key_borrowing_system/tree/main/public/html) (Web interface), [`public/js/admin-script.js`](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/js/admin-script.js) (Admin console), [`public/js/scan-script.js`](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/js/scan-script.js) (QR scanning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web interface"]
  node_scan["QR scanning<br/>[scan-script.js]"]
  node_adminui["Admin console<br/>[admin-script.js]"]
  node_dashboard["Dashboard"]
end

subgraph group_api["Application API"]
  node_server["API server<br/>[server.js]"]
end

subgraph group_records["Domain records"]
  node_users[("User accounts<br/>[User.js]")]
  node_admins[("Admin accounts<br/>[Admin.js]")]
  node_keys[("Keys<br/>[Key.js]")]
  node_lockers[("Lockers<br/>[Locker.js]")]
  node_qrcodes[("QR codes<br/>[QRCode.js]")]
  node_transactions[("Transactions<br/>[Transaction.js]")]
  node_activity[("Activity logs<br/>[ActivityLog.js]")]
  node_announcements[("Announcements<br/>[Announcement.js]")]
  node_feedback[("Feedback<br/>[Feedback.js]")]
  node_maintenance[("Maintenance<br/>[Maintenance.js]")]
  node_lostreports[("Lost reports<br/>[LostReport.js]")]
end

subgraph group_device["Locker device"]
  node_esp["ESP32 controller<br/>[main.c]"]
  node_dns["Captive DNS<br/>[dns_server.c]"]
end

node_user(("Key borrower"))
node_admin(("Administrator"))
node_mongodb[("MongoDB")]

node_user -->|"uses"| node_webapp
node_admin -->|"uses"| node_webapp
node_webapp -->|"scans QR"| node_scan
node_webapp -->|"administers"| node_adminui
node_adminui -->|"views reports"| node_dashboard
node_scan -->|"records transactions"| node_server
node_adminui -->|"manages records"| node_server
node_dashboard -->|"requests status"| node_server
node_server -->|"connects"| node_mongodb
node_server -->|"uses"| node_users
node_server -->|"uses"| node_admins
node_server -->|"uses"| node_keys
node_server -->|"uses"| node_lockers
node_server -->|"uses"| node_qrcodes
node_server -->|"uses"| node_transactions
node_server -->|"uses"| node_activity
node_server -->|"uses"| node_announcements
node_server -->|"uses"| node_feedback
node_server -->|"uses"| node_maintenance
node_server -->|"uses"| node_lostreports
node_server -.->|"controls lockers"| node_esp
node_esp -.->|"uses captive DNS"| node_dns

click node_webapp "https://github.com/dwarffyz/key_borrowing_system/tree/main/public/html"
click node_scan "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/js/scan-script.js"
click node_adminui "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/js/admin-script.js"
click node_dashboard "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/js/dashboard-script.js"
click node_server "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/server.js"
click node_users "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/User.js"
click node_admins "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Admin.js"
click node_keys "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Key.js"
click node_lockers "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Locker.js"
click node_qrcodes "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/QRCode.js"
click node_transactions "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Transaction.js"
click node_activity "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/ActivityLog.js"
click node_announcements "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Announcement.js"
click node_feedback "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Feedback.js"
click node_maintenance "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Maintenance.js"
click node_lostreports "https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/LostReport.js"
click node_esp "https://github.com/dwarffyz/key_borrowing_system/blob/main/hardware/esp32-locker-controller/main.c"
click node_dns "https://github.com/dwarffyz/key_borrowing_system/blob/main/hardware/esp32-locker-controller/components/dns_server/dns_server.c"

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_webapp,node_scan,node_adminui,node_dashboard toneBlue
class node_server,node_mongodb toneAmber
class node_users,node_admins,node_keys,node_lockers,node_qrcodes,node_transactions,node_activity,node_announcements,node_feedback,node_maintenance,node_lostreports toneMint
class node_esp,node_dns toneRose
class node_user,node_admin toneIndigo
```

## Components

### Web experience

- [Web interface](https://github.com/dwarffyz/key_borrowing_system/tree/main/public/html): `public/html`
- [QR scanning](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/js/scan-script.js): `public/js/scan-script.js`
- [Admin console](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/js/admin-script.js): `public/js/admin-script.js`
- [Dashboard](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/js/dashboard-script.js): `public/js/dashboard-script.js`

### Application API

- [API server](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/server.js): `public/server/server.js`

### Domain records

- [User accounts](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/User.js): `public/server/models/User.js`
- [Admin accounts](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Admin.js): `public/server/models/Admin.js`
- [Keys](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Key.js): `public/server/models/Key.js`
- [Lockers](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Locker.js): `public/server/models/Locker.js`
- [QR codes](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/QRCode.js): `public/server/models/QRCode.js`
- [Transactions](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Transaction.js): `public/server/models/Transaction.js`
- [Activity logs](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/ActivityLog.js): `public/server/models/ActivityLog.js`
- [Announcements](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Announcement.js): `public/server/models/Announcement.js`
- [Feedback](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Feedback.js): `public/server/models/Feedback.js`
- [Maintenance](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/Maintenance.js): `public/server/models/Maintenance.js`
- [Lost reports](https://github.com/dwarffyz/key_borrowing_system/blob/main/public/server/models/LostReport.js): `public/server/models/LostReport.js`

### Locker device

- [ESP32 controller](https://github.com/dwarffyz/key_borrowing_system/blob/main/hardware/esp32-locker-controller/main.c): `hardware/esp32-locker-controller/main.c`
- [Captive DNS](https://github.com/dwarffyz/key_borrowing_system/blob/main/hardware/esp32-locker-controller/components/dns_server/dns_server.c): `hardware/esp32-locker-controller/components/dns_server/dns_server.c`

### Other components

- **Key borrower**
- **Administrator**
- **MongoDB**

## Connections

- Key borrower → Web interface: uses (evidence: `README.md`)
- Administrator → Web interface: uses (evidence: `README.md`)
- Web interface → QR scanning: scans QR (evidence: `README.md`)
- Web interface → Admin console: administers (evidence: `README.md`)
- Admin console → Dashboard: views reports (evidence: `README.md`)
- QR scanning → API server: records transactions (evidence: `README.md`)
- Admin console → API server: manages records (evidence: `README.md`)
- Dashboard → API server: requests status (evidence: `README.md`)
- API server → MongoDB: connects (evidence: `public/server/server.js`)
- API server → User accounts: uses (evidence: `public/server/server.js`)
- API server → Admin accounts: uses (evidence: `public/server/server.js`)
- API server → Keys: uses (evidence: `public/server/server.js`)
- API server → Lockers: uses (evidence: `public/server/server.js`)
- API server → QR codes: uses (evidence: `public/server/server.js`)
- API server → Transactions: uses (evidence: `public/server/server.js`)
- API server → Activity logs: uses (evidence: `public/server/server.js`)
- API server → Announcements: uses (evidence: `public/server/server.js`)
- API server → Feedback: uses (evidence: `public/server/server.js`)
- API server → Maintenance: uses (evidence: `public/server/server.js`)
- API server → Lost reports: uses (evidence: `public/server/server.js`)
- API server → ESP32 controller: controls lockers (evidence: `README.md`)
- ESP32 controller → Captive DNS: uses captive DNS
