# mxxham/wms architecture

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

- Interactive diagram: https://gitdiagram.com/mxxham/wms
- Repository: https://github.com/mxxham/wms

## Overview

CKB Warehouse is a warehouse-management application for Shell lubricant stock. Operators scan and inspect bins, record receiving and stock movements, and use inventory and audit screens to monitor stock. The central planning workflow loads stock and demand, runs FEFO allocation and picklist planning, then saves plans for wave execution; README documents idempotent posting into the movements ledger. The app also provides bin labels, 3D warehouse visualization, counts, traceability, data-quality checks, and administration. Unsampled feature pages are represented by their exact directories; those branches are based on README capabilities, not inspected implementations.

Main entry points: [`lib/allocator/browser/plan-client.ts`](https://github.com/mxxham/wms/blob/integrate-bin-system/lib/allocator/browser/plan-client.ts) (Plan coordination), [`app/(app)/bin/[code]`](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/bin/%5Bcode%5D) (Bin inspection), [`app/(app)/waves/waves-client.tsx`](https://github.com/mxxham/wms/blob/integrate-bin-system/app/(app)/waves/waves-client.tsx) (Wave execution), [`app/(app)/scan`](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/scan) (Scan bins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Warehouse operations"]
  node_scan["Scan bins"]
  node_bin["Bin inspection"]
  node_receiving["Receiving"]
  node_putaway["Putaway"]
  node_movement["Stock movements"]
  node_labels["Bin labels"]
  node_warehouse3d["3D warehouse<br/>[scene.tsx]"]
end

subgraph group_planning["Allocation and waves"]
  node_allocation_ui["Allocation planning"]
  node_plan_client["Plan coordination<br/>[plan-client.ts]"]
  node_stock_adapter["Stock adaptation<br/>[inventory-stock.ts]"]
  node_pipeline["Allocation pipeline<br/>[pipeline.ts]"]
  node_waves["Wave execution<br/>[waves-client.tsx]"]
end

subgraph group_oversight["Inventory oversight"]
  node_counts["Cycle counts"]
  node_inventory["Inventory control"]
  node_audits["Stock audits"]
  node_trace["Trace and export"]
  node_admin["Admin and imports"]
  node_quality["Data quality"]
end

subgraph group_platform["Data and presentation"]
  node_database[("Supabase database")]
  node_bin_data["Bin data access<br/>[bin-data.ts]"]
  node_warehouse_api["Warehouse API<br/>[route.ts]"]
end

node_operator(("Warehouse operator"))

node_operator -->|"scans locations"| node_scan
node_operator -->|"records receipts"| node_receiving
node_operator -->|"plans allocation"| node_allocation_ui
node_operator -->|"prints labels"| node_labels
node_operator -->|"views warehouse"| node_warehouse3d
node_operator -->|"counts stock"| node_counts
node_scan -.->|"opens bin"| node_bin
node_bin -->|"loads detail"| node_bin_data
node_bin_data -->|"reads bin data"| node_database
node_bin -->|"offers actions"| node_movement
node_movement -->|"posts movements"| node_database
node_receiving -.->|"records receipt"| node_database
node_putaway -.->|"records putaway"| node_database
node_allocation_ui -->|"requests plans"| node_plan_client
node_plan_client -->|"converts stock"| node_stock_adapter
node_plan_client -->|"runs planning"| node_pipeline
node_pipeline -->|"loads stock"| node_database
node_plan_client -->|"saves plan"| node_database
node_waves -->|"posts wave tasks"| node_database
node_waves -->|"replans waves"| node_plan_client
node_counts -.->|"records counts"| node_database
node_inventory -.->|"reads inventory"| node_database
node_audits -.->|"records audits"| node_database
node_trace -->|"queries movements"| node_database
node_labels -->|"loads label data"| node_database
node_warehouse_api -->|"reads warehouse data"| node_database
node_admin -.->|"manages warehouse data"| node_database
node_quality -.->|"checks data"| node_database

click node_scan "https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/scan"
click node_bin "https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/bin/%5Bcode%5D"
click node_receiving "https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/receiving"
click node_putaway "https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/putaway"
click node_movement "https://github.com/mxxham/wms/blob/integrate-bin-system/components/bin/movement-actions.tsx"
click node_labels "https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/labels"
click node_warehouse3d "https://github.com/mxxham/wms/blob/integrate-bin-system/components/warehouse/scene.tsx"
click node_allocation_ui "https://github.com/mxxham/wms/blob/integrate-bin-system/app/(app)/allocate/allocate-client.tsx"
click node_plan_client "https://github.com/mxxham/wms/blob/integrate-bin-system/lib/allocator/browser/plan-client.ts"
click node_stock_adapter "https://github.com/mxxham/wms/blob/integrate-bin-system/lib/allocator/adapters/inventory-stock.ts"
click node_pipeline "https://github.com/mxxham/wms/blob/integrate-bin-system/lib/allocator/pipeline.ts"
click node_waves "https://github.com/mxxham/wms/blob/integrate-bin-system/app/(app)/waves/waves-client.tsx"
click node_counts "https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/counts"
click node_inventory "https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/inventory"
click node_audits "https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/audit"
click node_trace "https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/trace"
click node_admin "https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/admin"
click node_quality "https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/data-quality"
click node_bin_data "https://github.com/mxxham/wms/blob/integrate-bin-system/lib/bin-data.ts"
click node_warehouse_api "https://github.com/mxxham/wms/blob/integrate-bin-system/app/api/warehouse/route.ts"

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_scan,node_bin,node_receiving,node_putaway,node_movement,node_labels,node_warehouse3d toneBlue
class node_allocation_ui,node_plan_client,node_stock_adapter,node_pipeline,node_waves toneAmber
class node_counts,node_inventory,node_audits,node_trace,node_admin,node_quality toneMint
class node_database,node_bin_data,node_warehouse_api toneRose
class node_operator toneIndigo
```

## Components

### Warehouse operations

- [Scan bins](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/scan): `app/(app)/scan`
- [Bin inspection](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/bin/%5Bcode%5D): `app/(app)/bin/[code]`
- [Receiving](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/receiving): `app/(app)/receiving`
- [Putaway](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/putaway): `app/(app)/putaway`
- [Stock movements](https://github.com/mxxham/wms/blob/integrate-bin-system/components/bin/movement-actions.tsx): `components/bin/movement-actions.tsx`
- [Bin labels](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/labels): `app/(app)/labels`
- [3D warehouse](https://github.com/mxxham/wms/blob/integrate-bin-system/components/warehouse/scene.tsx): `components/warehouse/scene.tsx`

### Allocation and waves

- [Allocation planning](https://github.com/mxxham/wms/blob/integrate-bin-system/app/(app)/allocate/allocate-client.tsx): `app/(app)/allocate/allocate-client.tsx`
- [Plan coordination](https://github.com/mxxham/wms/blob/integrate-bin-system/lib/allocator/browser/plan-client.ts): `lib/allocator/browser/plan-client.ts`
- [Stock adaptation](https://github.com/mxxham/wms/blob/integrate-bin-system/lib/allocator/adapters/inventory-stock.ts): `lib/allocator/adapters/inventory-stock.ts`
- [Allocation pipeline](https://github.com/mxxham/wms/blob/integrate-bin-system/lib/allocator/pipeline.ts): `lib/allocator/pipeline.ts`
- [Wave execution](https://github.com/mxxham/wms/blob/integrate-bin-system/app/(app)/waves/waves-client.tsx): `app/(app)/waves/waves-client.tsx`

### Inventory oversight

- [Cycle counts](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/counts): `app/(app)/counts`
- [Inventory control](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/inventory): `app/(app)/inventory`
- [Stock audits](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/audit): `app/(app)/audit`
- [Trace and export](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/trace): `app/(app)/trace`
- [Admin and imports](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/admin): `app/(app)/admin`
- [Data quality](https://github.com/mxxham/wms/tree/integrate-bin-system/app/(app)/data-quality): `app/(app)/data-quality`

### Data and presentation

- **Supabase database**
- [Bin data access](https://github.com/mxxham/wms/blob/integrate-bin-system/lib/bin-data.ts): `lib/bin-data.ts`
- [Warehouse API](https://github.com/mxxham/wms/blob/integrate-bin-system/app/api/warehouse/route.ts): `app/api/warehouse/route.ts`

### Other components

- **Warehouse operator**

## Connections

- Warehouse operator → Scan bins: scans locations (evidence: `README.md`)
- Warehouse operator → Receiving: records receipts (evidence: `README.md`)
- Warehouse operator → Allocation planning: plans allocation (evidence: `README.md`)
- Warehouse operator → Bin labels: prints labels (evidence: `README.md`)
- Warehouse operator → 3D warehouse: views warehouse (evidence: `README.md`)
- Warehouse operator → Cycle counts: counts stock (evidence: `README.md`)
- Scan bins → Bin inspection: opens bin
- Bin inspection → Bin data access: loads detail (evidence: `app/(app)/bin/[code]/bin-page-client.tsx`)
- Bin data access → Supabase database: reads bin data
- Bin inspection → Stock movements: offers actions (evidence: `components/bin/movement-actions.tsx`)
- Stock movements → Supabase database: posts movements (evidence: `components/bin/movement-actions.tsx`)
- Receiving → Supabase database: records receipt
- Putaway → Supabase database: records putaway
- Allocation planning → Plan coordination: requests plans (evidence: `app/(app)/allocate/allocate-client.tsx`)
- Plan coordination → Stock adaptation: converts stock (evidence: `lib/allocator/browser/plan-client.ts`)
- Plan coordination → Allocation pipeline: runs planning (evidence: `lib/allocator/browser/plan-client.ts`)
- Allocation pipeline → Supabase database: loads stock
- Plan coordination → Supabase database: saves plan (evidence: `lib/allocator/browser/plan-client.ts`)
- Wave execution → Supabase database: posts wave tasks (evidence: `README.md`)
- Wave execution → Plan coordination: replans waves (evidence: `app/(app)/waves/waves-client.tsx`)
- Cycle counts → Supabase database: records counts
- Inventory control → Supabase database: reads inventory
- Stock audits → Supabase database: records audits
- Trace and export → Supabase database: queries movements
- Bin labels → Supabase database: loads label data
- Warehouse API → Supabase database: reads warehouse data (evidence: `app/api/warehouse/route.ts`)
- Admin and imports → Supabase database: manages warehouse data
- Data quality → Supabase database: checks data