# pallab-js/wms architecture

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

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

## Overview

WarehouseOS is a native macOS warehouse-management app. Users manage sites, inventory, employees, and transfers through SwiftUI screens; view models invoke services for business rules, which use repository protocols backed by atomic JSON files. The README documents the broad MVVM/service/repository flow; sampled source confirms transfer-state mutations and atomic inventory persistence, and reports aggregation. Several feature and service links are based on the documented architecture and capability descriptions rather than sampled implementations.

Main entry points: [`Sources/WarehouseOSApp/AppRouter.swift`](https://github.com/pallab-js/wms/blob/main/Sources/WarehouseOSApp/AppRouter.swift) (App navigation), [`Packages/WMSCore/Sources/WMSCore/Protocols`](https://github.com/pallab-js/wms/tree/main/Packages/WMSCore/Sources/WMSCore/Protocols) (Repository protocols), [`Packages/WMSServices/Sources/WMSServices/ReportsService.swift`](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/ReportsService.swift) (Reports aggregation), [`Packages/WMSServices/Sources/WMSServices/TransferService.swift`](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/TransferService.swift) (Transfer workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["User interface"]
  node_inventoryui["Inventory screens"]
  node_warehouseui["Warehouse screens"]
  node_employeeui["Employee screens"]
  node_transferui["Transfer screens"]
  node_dashboardui["Dashboard screens"]
  node_reportsui["Reports screens<br/>[ReportsView.swift]"]
  node_auditui["Audit log screens"]
  node_searchui["Global search"]
  node_settingsui["Settings screens"]
end

subgraph group_operations["Warehouse operations"]
  node_inventoryservice["Inventory services"]
  node_movementservice["Stock movements"]
  node_transferservice["Transfer workflow"]
  node_warehouseservice["Warehouse services"]
  node_employeeservice["Employee services"]
  node_reportsservice["Reports aggregation"]
  node_dashboardservice["Dashboard metrics"]
  node_auditservice["Audit logging"]
  node_alertservice["Low-stock alerts"]
  node_access["Role permissions"]
end

subgraph group_contracts["Domain contracts"]
  node_repos["Repository protocols"]
  node_domain["Domain models"]
end

subgraph group_storage["Local persistence"]
  node_datastore[("Atomic JSON store<br/>[DataStore.swift]")]
  node_filerepos["File repositories"]
  node_protection["Keychain protection"]
end

subgraph group_app["App services"]
  node_appshell["App navigation<br/>[AppRouter.swift]"]
  node_notifications["macOS notifications"]
end

node_user(("Warehouse user"))
node_osnotifications(("Notification Center"))

node_user -->|"navigates"| node_appshell
node_appshell -->|"opens"| node_inventoryui
node_appshell -->|"opens"| node_warehouseui
node_appshell -->|"opens"| node_employeeui
node_appshell -->|"opens"| node_transferui
node_appshell -->|"opens"| node_dashboardui
node_appshell -->|"opens"| node_reportsui
node_appshell -->|"opens"| node_auditui
node_appshell -->|"opens"| node_searchui
node_appshell -->|"opens"| node_settingsui
node_inventoryui -->|"requests operations"| node_inventoryservice
node_inventoryui -->|"records movements"| node_movementservice
node_warehouseui -->|"requests operations"| node_warehouseservice
node_employeeui -->|"requests operations"| node_employeeservice
node_transferui -->|"changes transfer"| node_transferservice
node_dashboardui -->|"requests metrics"| node_dashboardservice
node_reportsui -->|"requests reports"| node_reportsservice
node_auditui -->|"requests entries"| node_auditservice
node_searchui -->|"searches records"| node_warehouseservice
node_searchui -->|"searches records"| node_inventoryservice
node_searchui -->|"searches records"| node_employeeservice
node_inventoryservice -->|"uses contracts"| node_repos
node_movementservice -->|"uses contracts"| node_repos
node_transferservice -->|"updates transfers"| node_repos
node_transferservice -->|"checks permissions"| node_access
node_transferservice -->|"records transitions"| node_auditservice
node_warehouseservice -->|"uses contracts"| node_repos
node_employeeservice -->|"uses contracts"| node_repos
node_dashboardservice -->|"loads metrics"| node_repos
node_reportsservice -->|"loads warehouses"| node_warehouseservice
node_reportsservice -->|"loads inventory"| node_inventoryservice
node_reportsservice -->|"loads movements"| node_movementservice
node_reportsservice -->|"loads transfers"| node_transferservice
node_auditservice -->|"uses contracts"| node_repos
node_alertservice -->|"posts alerts"| node_notifications
node_alertservice -->|"checks stock"| node_repos
node_repos -->|"exchanges models"| node_domain
node_filerepos -->|"implements"| node_repos
node_filerepos -->|"reads and writes"| node_datastore
node_datastore -.->|"protects data"| node_protection
node_notifications -->|"submits alerts"| node_osnotifications

click node_appshell "https://github.com/pallab-js/wms/blob/main/Sources/WarehouseOSApp/AppRouter.swift"
click node_inventoryui "https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Inventory"
click node_warehouseui "https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Warehouses"
click node_employeeui "https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Employees"
click node_transferui "https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Transfers"
click node_dashboardui "https://github.com/pallab-js/wms/blob/main/Packages/WMSFeatures/Sources/Reports/DashboardView.swift"
click node_reportsui "https://github.com/pallab-js/wms/blob/main/Packages/WMSFeatures/Sources/Reports/ReportsView.swift"
click node_auditui "https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/AuditLog"
click node_searchui "https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Search"
click node_settingsui "https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Settings"
click node_inventoryservice "https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/InventoryService.swift"
click node_movementservice "https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/StockMovementService.swift"
click node_transferservice "https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/TransferService.swift"
click node_warehouseservice "https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/WarehouseService.swift"
click node_employeeservice "https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/EmployeeService.swift"
click node_reportsservice "https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/ReportsService.swift"
click node_dashboardservice "https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/DashboardService.swift"
click node_auditservice "https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/AuditLogService.swift"
click node_alertservice "https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/InventoryAlertService.swift"
click node_access "https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/AccessController.swift"
click node_repos "https://github.com/pallab-js/wms/tree/main/Packages/WMSCore/Sources/WMSCore/Protocols"
click node_domain "https://github.com/pallab-js/wms/tree/main/Packages/WMSCore/Sources/WMSCore/Models"
click node_datastore "https://github.com/pallab-js/wms/blob/main/Packages/WMSData/Sources/WMSData/DataStore.swift"
click node_filerepos "https://github.com/pallab-js/wms/tree/main/Packages/WMSData/Sources/WMSData"
click node_protection "https://github.com/pallab-js/wms/blob/main/Packages/WMSData/Sources/WMSData/KeychainDataProtector.swift"
click node_notifications "https://github.com/pallab-js/wms/blob/main/Sources/WarehouseOSApp/NotificationManager.swift"

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_inventoryui,node_warehouseui,node_employeeui,node_transferui,node_dashboardui,node_reportsui,node_auditui,node_searchui,node_settingsui,node_user toneBlue
class node_inventoryservice,node_movementservice,node_transferservice,node_warehouseservice,node_employeeservice,node_reportsservice,node_dashboardservice,node_auditservice,node_alertservice,node_access toneAmber
class node_repos,node_domain toneMint
class node_datastore,node_filerepos,node_protection toneRose
class node_appshell,node_notifications,node_osnotifications toneIndigo
```

## Components

### User interface

- [Inventory screens](https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Inventory): `Packages/WMSFeatures/Sources/Inventory`
- [Warehouse screens](https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Warehouses): `Packages/WMSFeatures/Sources/Warehouses`
- [Employee screens](https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Employees): `Packages/WMSFeatures/Sources/Employees`
- [Transfer screens](https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Transfers): `Packages/WMSFeatures/Sources/Transfers`
- [Dashboard screens](https://github.com/pallab-js/wms/blob/main/Packages/WMSFeatures/Sources/Reports/DashboardView.swift): `Packages/WMSFeatures/Sources/Reports/DashboardView.swift`
- [Reports screens](https://github.com/pallab-js/wms/blob/main/Packages/WMSFeatures/Sources/Reports/ReportsView.swift): `Packages/WMSFeatures/Sources/Reports/ReportsView.swift`
- [Audit log screens](https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/AuditLog): `Packages/WMSFeatures/Sources/AuditLog`
- [Global search](https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Search): `Packages/WMSFeatures/Sources/Search`
- [Settings screens](https://github.com/pallab-js/wms/tree/main/Packages/WMSFeatures/Sources/Settings): `Packages/WMSFeatures/Sources/Settings`

### Warehouse operations

- [Inventory services](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/InventoryService.swift): `Packages/WMSServices/Sources/WMSServices/InventoryService.swift`
- [Stock movements](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/StockMovementService.swift): `Packages/WMSServices/Sources/WMSServices/StockMovementService.swift`
- [Transfer workflow](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/TransferService.swift): `Packages/WMSServices/Sources/WMSServices/TransferService.swift`
- [Warehouse services](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/WarehouseService.swift): `Packages/WMSServices/Sources/WMSServices/WarehouseService.swift`
- [Employee services](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/EmployeeService.swift): `Packages/WMSServices/Sources/WMSServices/EmployeeService.swift`
- [Reports aggregation](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/ReportsService.swift): `Packages/WMSServices/Sources/WMSServices/ReportsService.swift`
- [Dashboard metrics](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/DashboardService.swift): `Packages/WMSServices/Sources/WMSServices/DashboardService.swift`
- [Audit logging](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/AuditLogService.swift): `Packages/WMSServices/Sources/WMSServices/AuditLogService.swift`
- [Low-stock alerts](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/InventoryAlertService.swift): `Packages/WMSServices/Sources/WMSServices/InventoryAlertService.swift`
- [Role permissions](https://github.com/pallab-js/wms/blob/main/Packages/WMSServices/Sources/WMSServices/AccessController.swift): `Packages/WMSServices/Sources/WMSServices/AccessController.swift`

### Domain contracts

- [Repository protocols](https://github.com/pallab-js/wms/tree/main/Packages/WMSCore/Sources/WMSCore/Protocols): `Packages/WMSCore/Sources/WMSCore/Protocols`
- [Domain models](https://github.com/pallab-js/wms/tree/main/Packages/WMSCore/Sources/WMSCore/Models): `Packages/WMSCore/Sources/WMSCore/Models`

### Local persistence

- [Atomic JSON store](https://github.com/pallab-js/wms/blob/main/Packages/WMSData/Sources/WMSData/DataStore.swift): `Packages/WMSData/Sources/WMSData/DataStore.swift`
- [File repositories](https://github.com/pallab-js/wms/tree/main/Packages/WMSData/Sources/WMSData): `Packages/WMSData/Sources/WMSData`
- [Keychain protection](https://github.com/pallab-js/wms/blob/main/Packages/WMSData/Sources/WMSData/KeychainDataProtector.swift): `Packages/WMSData/Sources/WMSData/KeychainDataProtector.swift`

### App services

- [App navigation](https://github.com/pallab-js/wms/blob/main/Sources/WarehouseOSApp/AppRouter.swift): `Sources/WarehouseOSApp/AppRouter.swift`
- [macOS notifications](https://github.com/pallab-js/wms/blob/main/Sources/WarehouseOSApp/NotificationManager.swift): `Sources/WarehouseOSApp/NotificationManager.swift`

### Other components

- **Warehouse user**
- **Notification Center**

## Connections

- Warehouse user → App navigation: navigates
- App navigation → Inventory screens: opens
- App navigation → Warehouse screens: opens
- App navigation → Employee screens: opens
- App navigation → Transfer screens: opens
- App navigation → Dashboard screens: opens
- App navigation → Reports screens: opens
- App navigation → Audit log screens: opens
- App navigation → Global search: opens
- App navigation → Settings screens: opens
- Inventory screens → Inventory services: requests operations
- Inventory screens → Stock movements: records movements
- Warehouse screens → Warehouse services: requests operations
- Employee screens → Employee services: requests operations
- Transfer screens → Transfer workflow: changes transfer
- Dashboard screens → Dashboard metrics: requests metrics
- Reports screens → Reports aggregation: requests reports
- Audit log screens → Audit logging: requests entries
- Global search → Warehouse services: searches records
- Global search → Inventory services: searches records
- Global search → Employee services: searches records
- Inventory services → Repository protocols: uses contracts
- Stock movements → Repository protocols: uses contracts
- Transfer workflow → Repository protocols: updates transfers
- Transfer workflow → Role permissions: checks permissions
- Transfer workflow → Audit logging: records transitions
- Warehouse services → Repository protocols: uses contracts
- Employee services → Repository protocols: uses contracts
- Dashboard metrics → Repository protocols: loads metrics
- Reports aggregation → Warehouse services: loads warehouses
- Reports aggregation → Inventory services: loads inventory
- Reports aggregation → Stock movements: loads movements
- Reports aggregation → Transfer workflow: loads transfers
- Audit logging → Repository protocols: uses contracts
- Low-stock alerts → macOS notifications: posts alerts
- Low-stock alerts → Repository protocols: checks stock
- Repository protocols → Domain models: exchanges models
- File repositories → Repository protocols: implements
- File repositories → Atomic JSON store: reads and writes
- Atomic JSON store → Keychain protection: protects data
- macOS notifications → Notification Center: submits alerts