# atomichabit2023/keybox-system-production architecture

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

- Interactive diagram: https://gitdiagram.com/atomichabit2023/keybox-system-production
- Repository: https://github.com/atomichabit2023/keybox-system-production

## Overview

The repository implements a connected electronic keybox system: local firmware authenticates users, actuates locks, monitors doors, and synchronizes state; companion mobile and LINE LIFF interfaces support remote administration and QR access. The excerpts establish the firmware’s main orchestration and several controller interactions, plus QR generation’s Firebase lookup. Mobile, sync, and other LIFF wiring is not sampled, so those components are shown without speculative connections.

Main entry points: [`firmware/main.py`](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/main.py) (Main event loop), [`firmware/controllers/security_manager.py`](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/security_manager.py) (Intrusion monitoring), [`firmware/controllers/maintenance_manager.py`](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/maintenance_manager.py) (Local maintenance), [`firmware/controllers/sensor_manager.py`](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/sensor_manager.py) (Door sensing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["Keybox firmware"]
  node_main["Main event loop<br/>[main.py]"]
  node_auth["Local authentication<br/>[auth_manager.py]"]
  node_maintenance["Local maintenance"]
  node_security["Intrusion monitoring"]
  node_sensors["Door sensing<br/>[sensor_manager.py]"]
  node_doors["Lock actuation<br/>[door_manager.py]"]
  node_sync["Cloud synchronization<br/>[unified_sync.py]"]
  node_logger["Event logging<br/>[logger.py]"]
  node_ui["Local interface<br/>[ui_manager.py]"]
  node_rtc["Clock management<br/>[rtc_manager.py]"]
  node_wifi["Wi-Fi connectivity<br/>[wifi_manager.py]"]
  node_usersfile["Local user data<br/>[users.json]"]
end

subgraph group_cloud["Cloud and access"]
  node_firebase[("Firebase backend")]
  node_generator["Tenant provisioning"]
  node_liff["LINE access interface<br/>[index.html]"]
  node_qr["QR generation API<br/>[generate.py]"]
  node_register["LINE registration API<br/>[register.py]"]
  node_alert["LINE alert API<br/>[line_alert.py]"]
end

subgraph group_mobile["Mobile administration"]
  node_mobile["Mobile app<br/>[main.dart]"]
  node_mobileauth["Mobile authentication<br/>[auth_service.dart]"]
  node_tenant["Tenant management"]
end

subgraph group_hardware["Device hardware"]
  node_hardware["Lock and sensor hardware"]
end

node_resident(("Keybox user"))
node_admin(("Administrator"))

node_resident -->|"uses"| node_main
node_main -->|"validates credentials"| node_auth
node_main -->|"opens requested lock"| node_doors
node_main -->|"renders interface"| node_ui
node_main -->|"connects and checks"| node_wifi
node_main -->|"initializes clock"| node_rtc
node_main -->|"enters admin mode"| node_maintenance
node_main -->|"coordinates monitoring"| node_security
node_maintenance -->|"updates credentials"| node_auth
node_maintenance -->|"reads log history"| node_logger
node_security -->|"checks door state"| node_sensors
node_security -->|"updates box status"| node_sync
node_security -.->|"dispatches intrusion alert"| node_alert
node_sensors -->|"records state changes"| node_logger
node_auth -->|"reads and writes"| node_usersfile
node_doors -->|"pulses lock relay"| node_hardware
node_sensors -->|"reads door switches"| node_hardware
node_main -->|"initializes peripherals"| node_hardware
node_admin -->|"administers system"| node_mobile
node_mobile -->|"uses"| node_mobileauth
node_mobile -->|"manages tenants"| node_tenant
node_generator -->|"provisions tenant data"| node_firebase
node_liff -->|"requests access QR"| node_qr
node_qr -->|"looks up registered user"| node_firebase
node_register -.->|"registration integration"| node_firebase
node_sync -->|"cloud synchronization"| node_firebase

click node_main "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/main.py"
click node_auth "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/auth_manager.py"
click node_maintenance "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/maintenance_manager.py"
click node_security "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/security_manager.py"
click node_sensors "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/sensor_manager.py"
click node_doors "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/door_manager.py"
click node_sync "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/unified_sync.py"
click node_logger "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/logger.py"
click node_ui "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/ui_manager.py"
click node_rtc "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/rtc_manager.py"
click node_wifi "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/drivers/wifi_manager.py"
click node_usersfile "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/users.json"
click node_mobile "https://github.com/atomichabit2023/keybox-system-production/blob/main/mobile_app/lib/main.dart"
click node_mobileauth "https://github.com/atomichabit2023/keybox-system-production/blob/main/mobile_app/lib/services/auth_service.dart"
click node_tenant "https://github.com/atomichabit2023/keybox-system-production/blob/main/mobile_app/lib/services/tenant_manager.dart"
click node_generator "https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/universal_generator.py"
click node_liff "https://github.com/atomichabit2023/keybox-system-production/blob/main/keybox_liff/index.html"
click node_qr "https://github.com/atomichabit2023/keybox-system-production/blob/main/keybox_liff/api/generate.py"
click node_register "https://github.com/atomichabit2023/keybox-system-production/blob/main/keybox_liff/api/register.py"
click node_alert "https://github.com/atomichabit2023/keybox-system-production/blob/main/keybox_liff/api/line_alert.py"

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_main,node_auth,node_maintenance,node_security,node_sensors,node_doors,node_sync,node_logger,node_ui,node_rtc,node_wifi,node_usersfile,node_resident toneBlue
class node_firebase,node_generator,node_liff,node_qr,node_register,node_alert toneAmber
class node_mobile,node_mobileauth,node_tenant toneMint
class node_hardware toneRose
class node_admin toneIndigo
```

## Components

### Keybox firmware

- [Main event loop](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/main.py): `firmware/main.py`
- [Local authentication](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/auth_manager.py): `firmware/controllers/auth_manager.py`
- [Local maintenance](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/maintenance_manager.py): `firmware/controllers/maintenance_manager.py`
- [Intrusion monitoring](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/security_manager.py): `firmware/controllers/security_manager.py`
- [Door sensing](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/sensor_manager.py): `firmware/controllers/sensor_manager.py`
- [Lock actuation](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/door_manager.py): `firmware/controllers/door_manager.py`
- [Cloud synchronization](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/unified_sync.py): `firmware/controllers/unified_sync.py`
- [Event logging](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/logger.py): `firmware/controllers/logger.py`
- [Local interface](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/ui_manager.py): `firmware/controllers/ui_manager.py`
- [Clock management](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/controllers/rtc_manager.py): `firmware/controllers/rtc_manager.py`
- [Wi-Fi connectivity](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/drivers/wifi_manager.py): `firmware/drivers/wifi_manager.py`
- [Local user data](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/users.json): `firmware/users.json`

### Cloud and access

- **Firebase backend**
- [Tenant provisioning](https://github.com/atomichabit2023/keybox-system-production/blob/main/firmware/universal_generator.py): `firmware/universal_generator.py`
- [LINE access interface](https://github.com/atomichabit2023/keybox-system-production/blob/main/keybox_liff/index.html): `keybox_liff/index.html`
- [QR generation API](https://github.com/atomichabit2023/keybox-system-production/blob/main/keybox_liff/api/generate.py): `keybox_liff/api/generate.py`
- [LINE registration API](https://github.com/atomichabit2023/keybox-system-production/blob/main/keybox_liff/api/register.py): `keybox_liff/api/register.py`
- [LINE alert API](https://github.com/atomichabit2023/keybox-system-production/blob/main/keybox_liff/api/line_alert.py): `keybox_liff/api/line_alert.py`

### Mobile administration

- [Mobile app](https://github.com/atomichabit2023/keybox-system-production/blob/main/mobile_app/lib/main.dart): `mobile_app/lib/main.dart`
- [Mobile authentication](https://github.com/atomichabit2023/keybox-system-production/blob/main/mobile_app/lib/services/auth_service.dart): `mobile_app/lib/services/auth_service.dart`
- [Tenant management](https://github.com/atomichabit2023/keybox-system-production/blob/main/mobile_app/lib/services/tenant_manager.dart): `mobile_app/lib/services/tenant_manager.dart`

### Device hardware

- **Lock and sensor hardware**

### Other components

- **Keybox user**
- **Administrator**

## Connections

- Keybox user → Main event loop: uses
- Main event loop → Local authentication: validates credentials
- Main event loop → Lock actuation: opens requested lock
- Main event loop → Local interface: renders interface
- Main event loop → Wi-Fi connectivity: connects and checks
- Main event loop → Clock management: initializes clock
- Main event loop → Local maintenance: enters admin mode
- Main event loop → Intrusion monitoring: coordinates monitoring
- Local maintenance → Local authentication: updates credentials
- Local maintenance → Event logging: reads log history
- Intrusion monitoring → Door sensing: checks door state
- Intrusion monitoring → Cloud synchronization: updates box status
- Intrusion monitoring → LINE alert API: dispatches intrusion alert
- Door sensing → Event logging: records state changes
- Local authentication → Local user data: reads and writes
- Lock actuation → Lock and sensor hardware: pulses lock relay
- Door sensing → Lock and sensor hardware: reads door switches
- Main event loop → Lock and sensor hardware: initializes peripherals
- Administrator → Mobile app: administers system
- Mobile app → Mobile authentication: uses
- Mobile app → Tenant management: manages tenants
- Tenant provisioning → Firebase backend: provisions tenant data
- LINE access interface → QR generation API: requests access QR
- QR generation API → Firebase backend: looks up registered user
- LINE registration API → Firebase backend: registration integration
- Cloud synchronization → Firebase backend: cloud synchronization