# franstio/timbangan-step-2-api architecture

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

- Interactive diagram: https://gitdiagram.com/franstio/timbangan-step-2-api
- Repository: https://github.com/franstio/timbangan-step-2-api

## Overview

This is a Node/Express service for a waste-handling installation: operators scan badges and containers, record or update waste transactions, and monitor bin weights. The runtime also reads two serial scales, serves live bin-weight updates, and synchronizes employees, bins, containers, and pending transactions with external systems. The graph follows the sampled route, controller, and startup wiring; several synchronization implementations are only partially shown, so uncertain internal calls are omitted.

Main entry points: [`controllers/Employee.js`](https://github.com/franstio/timbangan-step-2-api/blob/master/controllers/Employee.js) (Transaction workflows), [`controllers/Bin.js`](https://github.com/franstio/timbangan-step-2-api/blob/master/controllers/Bin.js) (Bin operations), [`index.js`](https://github.com/franstio/timbangan-step-2-api/blob/master/index.js) (HTTP and job runtime), [`routes/APIRoute.js`](https://github.com/franstio/timbangan-step-2-api/blob/master/routes/APIRoute.js) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Operator API"]
  node_server["HTTP and job runtime<br/>[index.js]"]
  node_scanner_routes["Scanner routes<br/>[ScannerRoute.js]"]
  node_api_routes["API routes<br/>[APIRoute.js]"]
end

subgraph group_hardware["Weight Monitoring"]
  node_bin_ctrl["Bin operations<br/>[Bin.js]"]
  node_scales_ctrl["Scale readers<br/>[Scales.js]"]
end

subgraph group_domain["Waste Records"]
  node_employee_ctrl["Transaction workflows<br/>[Employee.js]"]
  node_bin_model["Bin records<br/>[BinModel.js]"]
  node_container_model["Container records<br/>[ContainerModel.js]"]
  node_waste_model["Waste types<br/>[WasteModel.js]"]
  node_employee_model["Employee records<br/>[EmployeeModel.js]"]
  node_transaction_model["Transaction records"]
  node_db_config["Database connection<br/>[db.js]"]
end

subgraph group_sync["Synchronization"]
  node_job_queues["Background queues<br/>[index.js]"]
end

node_operator(("Operator / client"))
node_scale_devices{{"Serial scales"}}
node_socket_clients(("Bin clients"))
node_mysql[("MySQL database")]
node_pidsg{{"PIDSG service"}}
node_step1{{"Step 1 service"}}
node_step3{{"Step 3 service"}}
node_rack_api{{"Rack API"}}
node_redis[("Redis password store")]

node_operator -->|"sends requests"| node_scanner_routes
node_operator -->|"sends requests"| node_api_routes
node_server -->|"mounts routes"| node_scanner_routes
node_server -->|"mounts routes"| node_api_routes
node_scanner_routes -->|"dispatches handlers"| node_employee_ctrl
node_scanner_routes -->|"dispatches handlers"| node_bin_ctrl
node_api_routes -->|"dispatches handlers"| node_employee_ctrl
node_api_routes -->|"dispatches handlers"| node_bin_ctrl
node_api_routes -->|"dispatches reset"| node_scales_ctrl
node_server -->|"authenticates"| node_db_config
node_db_config -->|"connects"| node_mysql
node_employee_ctrl -->|"queries"| node_employee_model
node_employee_ctrl -->|"queries"| node_container_model
node_employee_ctrl -->|"queries"| node_bin_model
node_employee_ctrl -->|"records transactions"| node_transaction_model
node_bin_ctrl -->|"reads bin state"| node_bin_model
node_server -->|"starts readers"| node_scales_ctrl
node_scales_ctrl -->|"reads serial data"| node_scale_devices
node_scales_ctrl -->|"requeues reads"| node_job_queues
node_server -->|"schedules jobs"| node_job_queues
node_job_queues -->|"runs sync jobs"| node_employee_ctrl
node_job_queues -->|"runs scale jobs"| node_scales_ctrl
node_job_queues -->|"runs weight updates"| node_bin_ctrl
node_job_queues -->|"posts sync payloads"| node_rack_api
node_employee_ctrl -->|"syncs records"| node_pidsg
node_employee_ctrl -->|"fetches and updates logs"| node_step1
node_employee_ctrl -->|"updates values"| node_step3
node_employee_ctrl -->|"updates bin weights"| node_bin_ctrl
node_socket_clients -->|"opens socket"| node_server
node_server -->|"registers weight listener"| node_bin_ctrl
node_bin_ctrl -->|"emits weight updates"| node_socket_clients
node_bin_ctrl -->|"reads and writes password"| node_redis

click node_server "https://github.com/franstio/timbangan-step-2-api/blob/master/index.js"
click node_scanner_routes "https://github.com/franstio/timbangan-step-2-api/blob/master/routes/ScannerRoute.js"
click node_api_routes "https://github.com/franstio/timbangan-step-2-api/blob/master/routes/APIRoute.js"
click node_employee_ctrl "https://github.com/franstio/timbangan-step-2-api/blob/master/controllers/Employee.js"
click node_bin_ctrl "https://github.com/franstio/timbangan-step-2-api/blob/master/controllers/Bin.js"
click node_scales_ctrl "https://github.com/franstio/timbangan-step-2-api/blob/master/controllers/Scales.js"
click node_bin_model "https://github.com/franstio/timbangan-step-2-api/blob/master/models/BinModel.js"
click node_container_model "https://github.com/franstio/timbangan-step-2-api/blob/master/models/ContainerModel.js"
click node_waste_model "https://github.com/franstio/timbangan-step-2-api/blob/master/models/WasteModel.js"
click node_employee_model "https://github.com/franstio/timbangan-step-2-api/blob/master/models/EmployeeModel.js"
click node_transaction_model "https://github.com/franstio/timbangan-step-2-api/blob/master/models/TransactionModel.js"
click node_db_config "https://github.com/franstio/timbangan-step-2-api/blob/master/config/db.js"
click node_job_queues "https://github.com/franstio/timbangan-step-2-api/blob/master/index.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_server,node_scanner_routes,node_api_routes,node_operator,node_socket_clients toneBlue
class node_bin_ctrl,node_scales_ctrl,node_mysql,node_redis toneAmber
class node_employee_ctrl,node_bin_model,node_container_model,node_waste_model,node_employee_model,node_transaction_model,node_db_config,node_rack_api toneMint
class node_job_queues toneRose
class node_scale_devices,node_pidsg,node_step1,node_step3 toneIndigo
```

## Components

### Operator API

- [HTTP and job runtime](https://github.com/franstio/timbangan-step-2-api/blob/master/index.js): `index.js`
- [Scanner routes](https://github.com/franstio/timbangan-step-2-api/blob/master/routes/ScannerRoute.js): `routes/ScannerRoute.js`
- [API routes](https://github.com/franstio/timbangan-step-2-api/blob/master/routes/APIRoute.js): `routes/APIRoute.js`

### Weight Monitoring

- [Bin operations](https://github.com/franstio/timbangan-step-2-api/blob/master/controllers/Bin.js): `controllers/Bin.js`
- [Scale readers](https://github.com/franstio/timbangan-step-2-api/blob/master/controllers/Scales.js): `controllers/Scales.js`

### Waste Records

- [Transaction workflows](https://github.com/franstio/timbangan-step-2-api/blob/master/controllers/Employee.js): `controllers/Employee.js`
- [Bin records](https://github.com/franstio/timbangan-step-2-api/blob/master/models/BinModel.js): `models/BinModel.js`
- [Container records](https://github.com/franstio/timbangan-step-2-api/blob/master/models/ContainerModel.js): `models/ContainerModel.js`
- [Waste types](https://github.com/franstio/timbangan-step-2-api/blob/master/models/WasteModel.js): `models/WasteModel.js`
- [Employee records](https://github.com/franstio/timbangan-step-2-api/blob/master/models/EmployeeModel.js): `models/EmployeeModel.js`
- [Transaction records](https://github.com/franstio/timbangan-step-2-api/blob/master/models/TransactionModel.js): `models/TransactionModel.js`
- [Database connection](https://github.com/franstio/timbangan-step-2-api/blob/master/config/db.js): `config/db.js`

### Synchronization

- [Background queues](https://github.com/franstio/timbangan-step-2-api/blob/master/index.js): `index.js`

### Other components

- **Operator / client**
- **Serial scales**
- **Bin clients**
- **MySQL database**
- **PIDSG service**
- **Step 1 service**
- **Step 3 service**
- **Rack API**
- **Redis password store**

## Connections

- Operator / client → Scanner routes: sends requests
- Operator / client → API routes: sends requests
- HTTP and job runtime → Scanner routes: mounts routes
- HTTP and job runtime → API routes: mounts routes
- Scanner routes → Transaction workflows: dispatches handlers
- Scanner routes → Bin operations: dispatches handlers
- API routes → Transaction workflows: dispatches handlers
- API routes → Bin operations: dispatches handlers
- API routes → Scale readers: dispatches reset
- HTTP and job runtime → Database connection: authenticates
- Database connection → MySQL database: connects
- Transaction workflows → Employee records: queries
- Transaction workflows → Container records: queries
- Transaction workflows → Bin records: queries
- Transaction workflows → Transaction records: records transactions
- Bin operations → Bin records: reads bin state
- HTTP and job runtime → Scale readers: starts readers
- Scale readers → Serial scales: reads serial data
- Scale readers → Background queues: requeues reads
- HTTP and job runtime → Background queues: schedules jobs
- Background queues → Transaction workflows: runs sync jobs
- Background queues → Scale readers: runs scale jobs
- Background queues → Bin operations: runs weight updates
- Background queues → Rack API: posts sync payloads
- Transaction workflows → PIDSG service: syncs records
- Transaction workflows → Step 1 service: fetches and updates logs
- Transaction workflows → Step 3 service: updates values
- Transaction workflows → Bin operations: updates bin weights
- Bin clients → HTTP and job runtime: opens socket
- HTTP and job runtime → Bin operations: registers weight listener
- Bin operations → Bin clients: emits weight updates
- Bin operations → Redis password store: reads and writes password