# dekoithub/warehouse-sorter architecture

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

- Interactive diagram: https://gitdiagram.com/dekoithub/warehouse-sorter
- Repository: https://github.com/dekoithub/warehouse-sorter

## Overview

warehouse-sorter is a warehouse parcel-sorting simulation. In the principal workflow, src/main.py drives item creation and sensor detection; the controller scans and requests a route from the WMS, dispatches parcels to conveyors or buffers, and handles sorter events to place parcels in output bins or manual processing. Statistics collect processing and load metrics for a final report. The README names no further capabilities; architecture reflects the sampled source, so unsampled runtime details are not inferred.

Main entry points: [`src/models/controller.py`](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/controller.py) (Workflow controller), [`src/models/item.py`](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/item.py) (Parcel state), [`src/main.py`](https://github.com/dekoithub/warehouse-sorter/blob/main/src/main.py) (Simulation runner), [`src/models/sensor.py`](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/sensor.py) (Sensors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Simulation flow"]
  node_main["Simulation runner<br/>[main.py]"]
  node_controller["Workflow controller<br/>[controller.py]"]
end

subgraph group_routing["Scan and routing"]
  node_sensor["Sensors<br/>[sensor.py]"]
  node_scanner["Barcode scanner<br/>[scanner.py]"]
  node_wms["Route lookup<br/>[wms.py]"]
end

subgraph group_equipment["Material handling"]
  node_conveyor["Conveyors<br/>[conveyor.py]"]
  node_buffer["Buffer storage<br/>[buffer.py]"]
  node_sorter["Parcel sorter<br/>[sorter.py]"]
  node_output["Output bins<br/>[output_bin.py]"]
  node_manual["Manual processing<br/>[controller.py]"]
end

subgraph group_domain["Items and reporting"]
  node_item["Parcel state<br/>[item.py]"]
  node_statistics["Metrics and report<br/>[statistics.py]"]
end

node_operator(("Simulation operator"))

node_operator -.->|"runs simulation"| node_main
node_main -->|"creates parcels"| node_item
node_main -->|"drives workflow"| node_controller
node_main -->|"detects and signals"| node_sensor
node_controller -->|"processes events"| node_sensor
node_controller -->|"scans parcels"| node_scanner
node_controller -->|"requests destination"| node_wms
node_controller -->|"dispatches parcels"| node_conveyor
node_controller -->|"stores or releases"| node_buffer
node_controller -->|"sorts parcels"| node_sorter
node_controller -->|"places sorted parcels"| node_output
node_controller -->|"sends exceptions"| node_manual
node_controller -->|"updates metrics"| node_statistics
node_main -->|"reports results"| node_statistics
node_controller -->|"updates parcel state"| node_item
node_sensor -->|"identifies parcel"| node_item
node_conveyor -->|"holds parcels"| node_item
node_buffer -->|"holds parcels"| node_item
node_sorter -->|"changes direction"| node_item
node_output -->|"stores parcels"| node_item

click node_main "https://github.com/dekoithub/warehouse-sorter/blob/main/src/main.py"
click node_controller "https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/controller.py"
click node_item "https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/item.py"
click node_sensor "https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/sensor.py"
click node_scanner "https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/scanner.py"
click node_wms "https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/wms.py"
click node_conveyor "https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/conveyor.py"
click node_buffer "https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/buffer.py"
click node_sorter "https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/sorter.py"
click node_output "https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/output_bin.py"
click node_statistics "https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/statistics.py"
click node_manual "https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/controller.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_controller toneBlue
class node_sensor,node_scanner,node_wms toneAmber
class node_conveyor,node_buffer,node_sorter,node_output,node_manual toneMint
class node_item,node_statistics toneRose
class node_operator toneIndigo
```

## Components

### Simulation flow

- [Simulation runner](https://github.com/dekoithub/warehouse-sorter/blob/main/src/main.py): `src/main.py`
- [Workflow controller](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/controller.py): `src/models/controller.py`

### Scan and routing

- [Sensors](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/sensor.py): `src/models/sensor.py`
- [Barcode scanner](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/scanner.py): `src/models/scanner.py`
- [Route lookup](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/wms.py): `src/models/wms.py`

### Material handling

- [Conveyors](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/conveyor.py): `src/models/conveyor.py`
- [Buffer storage](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/buffer.py): `src/models/buffer.py`
- [Parcel sorter](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/sorter.py): `src/models/sorter.py`
- [Output bins](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/output_bin.py): `src/models/output_bin.py`
- [Manual processing](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/controller.py): `src/models/controller.py`

### Items and reporting

- [Parcel state](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/item.py): `src/models/item.py`
- [Metrics and report](https://github.com/dekoithub/warehouse-sorter/blob/main/src/models/statistics.py): `src/models/statistics.py`

### Other components

- **Simulation operator**

## Connections

- Simulation operator → Simulation runner: runs simulation
- Simulation runner → Parcel state: creates parcels (evidence: `src/main.py`)
- Simulation runner → Workflow controller: drives workflow (evidence: `src/main.py`)
- Simulation runner → Sensors: detects and signals (evidence: `src/main.py`)
- Workflow controller → Sensors: processes events (evidence: `src/main.py`)
- Workflow controller → Barcode scanner: scans parcels (evidence: `src/models/controller.py`)
- Workflow controller → Route lookup: requests destination (evidence: `src/models/controller.py`)
- Workflow controller → Conveyors: dispatches parcels (evidence: `src/models/controller.py`)
- Workflow controller → Buffer storage: stores or releases (evidence: `src/models/controller.py`)
- Workflow controller → Parcel sorter: sorts parcels (evidence: `src/models/controller.py`)
- Workflow controller → Output bins: places sorted parcels (evidence: `src/models/controller.py`)
- Workflow controller → Manual processing: sends exceptions (evidence: `src/models/controller.py`)
- Workflow controller → Metrics and report: updates metrics (evidence: `src/models/controller.py`)
- Simulation runner → Metrics and report: reports results (evidence: `src/main.py`)
- Workflow controller → Parcel state: updates parcel state (evidence: `src/models/controller.py`)
- Sensors → Parcel state: identifies parcel (evidence: `src/models/sensor.py`)
- Conveyors → Parcel state: holds parcels (evidence: `src/models/conveyor.py`)
- Buffer storage → Parcel state: holds parcels (evidence: `src/models/buffer.py`)
- Parcel sorter → Parcel state: changes direction (evidence: `src/models/sorter.py`)
- Output bins → Parcel state: stores parcels (evidence: `src/models/output_bin.py`)
