# therealmoronto/nimbo-wms architecture

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

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

## Overview

Nimbo is a warehouse-management system whose current product surface centers on API-driven warehouse operations: users manage master data and warehouse topology, then create and query receiving, shipping, relocation, adjustment, and cycle-count documents. Posting those documents updates stock through the documented double-entry ledger; stock-lot availability can be queried for picking. The graph shows the API, contracts, domain, use cases, persistence, and outbox as distinct layers. Some command-dispatch and posting wiring is not shown in the excerpts, so those links are marked unverified or omitted.

Main entry points: [`Nimbo.Wms/Controllers`](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms/Controllers) (HTTP API), [`Nimbo.Wms.Contracts`](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Contracts) (Request contracts), [`Nimbo.Wms.Infrastructure/UseCases/Stock/Handlers/GetAvailableStockLotsQueryHandler.cs`](https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.Infrastructure/UseCases/Stock/Handlers/GetAvailableStockLotsQueryHandler.cs) (Available lots), [`Nimbo.Wms.Application/Services/Documents`](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Application/Services/Documents) (WMS documents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_webapi["HTTP API<br/>[Controllers]"]
  node_contracts["Request contracts"]
  node_result["Result handling<br/>[Result.cs]"]
end

subgraph group_application["Use cases"]
  node_masterdata["Master data"]
  node_topology["Warehouse topology<br/>[Topology]"]
  node_documents["WMS documents<br/>[Documents]"]
  node_stockquery["Available lots"]
  node_mapping["DTO mapping<br/>[Mappings]"]
  node_posting["Document posting<br/>[Documents]"]
end

subgraph group_domain["Warehouse domain"]
  node_masterentities["Master entities<br/>[MasterData]"]
  node_topologyentities["Topology entities<br/>[Topology]"]
  node_documententities["Document aggregates<br/>[Documents]"]
  node_inventory["Inventory lots<br/>[Stock]"]
  node_quantity["Quantity rules<br/>[Quantity.cs]"]
  node_identifiers["Typed identifiers<br/>[Identification]"]
  node_ledger["Stock ledger"]
end

subgraph group_persistence["Persistence and events"]
  node_dbcontext["EF data context"]
  node_postgres[("PostgreSQL")]
  node_outbox["Outbox processor"]
  node_servicedefaults["Service defaults<br/>[Extensions.cs]"]
end

node_operator(("WMS user"))

node_operator -->|"uses"| node_webapi
node_webapi -->|"accepts requests"| node_contracts
node_webapi -->|"routes topology"| node_contracts
node_webapi -.->|"dispatches commands"| node_documents
node_contracts -.->|"dispatches queries"| node_masterdata
node_contracts -.->|"dispatches queries"| node_topology
node_contracts -.->|"dispatches documents"| node_documents
node_masterdata -.->|"manages"| node_masterentities
node_topology -->|"reads topology"| node_dbcontext
node_documents -.->|"handles documents"| node_documententities
node_stockquery -->|"queries lots"| node_dbcontext
node_stockquery -->|"selects stock"| node_inventory
node_stockquery -->|"maps quantities"| node_quantity
node_stockquery -->|"parses IDs"| node_identifiers
node_topology -->|"maps results"| node_mapping
node_documents -->|"maps results"| node_mapping
node_webapi -.->|"returns results"| node_result
node_posting -.->|"records movements"| node_ledger
node_posting -.->|"updates stock"| node_inventory
node_documententities -.->|"posts stock changes"| node_ledger
node_dbcontext -->|"persists data"| node_postgres
node_dbcontext -.->|"supplies event data"| node_outbox
node_webapi -->|"configures defaults"| node_servicedefaults

click node_webapi "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms/Controllers"
click node_contracts "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Contracts"
click node_result "https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.Contracts/Result.cs"
click node_masterdata "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Application"
click node_topology "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Infrastructure/UseCases/Topology"
click node_documents "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Application/Services/Documents"
click node_stockquery "https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.Infrastructure/UseCases/Stock/Handlers/GetAvailableStockLotsQueryHandler.cs"
click node_mapping "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Application/Mappings"
click node_posting "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Application/Services/Documents"
click node_masterentities "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Domain/Entities/MasterData"
click node_topologyentities "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Domain/Entities/Topology"
click node_documententities "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Domain/Entities/Documents"
click node_inventory "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Domain/Entities/Stock"
click node_quantity "https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.Domain/ValueObject/Quantity.cs"
click node_identifiers "https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Domain/Identification"
click node_ledger "https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.Domain/Entities/Ledger/StockLedgerEntry.cs"
click node_dbcontext "https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.Infrastructure/Persistence/NimboWmsDbContext.cs"
click node_outbox "https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.OutboxProcessor/OutboxBackgroundService.cs"
click node_servicedefaults "https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.ServiceDefaults/Extensions.cs"

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_webapi,node_contracts,node_result,node_operator toneBlue
class node_masterdata,node_topology,node_documents,node_stockquery,node_mapping,node_posting toneAmber
class node_masterentities,node_topologyentities,node_documententities,node_inventory,node_quantity,node_identifiers,node_ledger toneMint
class node_dbcontext,node_postgres,node_outbox,node_servicedefaults toneRose
```

## Components

### API surface

- [HTTP API](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms/Controllers): `Nimbo.Wms/Controllers`
- [Request contracts](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Contracts): `Nimbo.Wms.Contracts`
- [Result handling](https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.Contracts/Result.cs): `Nimbo.Wms.Contracts/Result.cs`

### Use cases

- [Master data](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Application): `Nimbo.Wms.Application`
- [Warehouse topology](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Infrastructure/UseCases/Topology): `Nimbo.Wms.Infrastructure/UseCases/Topology`
- [WMS documents](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Application/Services/Documents): `Nimbo.Wms.Application/Services/Documents`
- [Available lots](https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.Infrastructure/UseCases/Stock/Handlers/GetAvailableStockLotsQueryHandler.cs): `Nimbo.Wms.Infrastructure/UseCases/Stock/Handlers/GetAvailableStockLotsQueryHandler.cs`
- [DTO mapping](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Application/Mappings): `Nimbo.Wms.Application/Mappings`
- [Document posting](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Application/Services/Documents): `Nimbo.Wms.Application/Services/Documents`

### Warehouse domain

- [Master entities](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Domain/Entities/MasterData): `Nimbo.Wms.Domain/Entities/MasterData`
- [Topology entities](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Domain/Entities/Topology): `Nimbo.Wms.Domain/Entities/Topology`
- [Document aggregates](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Domain/Entities/Documents): `Nimbo.Wms.Domain/Entities/Documents`
- [Inventory lots](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Domain/Entities/Stock): `Nimbo.Wms.Domain/Entities/Stock`
- [Quantity rules](https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.Domain/ValueObject/Quantity.cs): `Nimbo.Wms.Domain/ValueObject/Quantity.cs`
- [Typed identifiers](https://github.com/therealmoronto/nimbo-wms/tree/main/Nimbo.Wms.Domain/Identification): `Nimbo.Wms.Domain/Identification`
- [Stock ledger](https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.Domain/Entities/Ledger/StockLedgerEntry.cs): `Nimbo.Wms.Domain/Entities/Ledger/StockLedgerEntry.cs`

### Persistence and events

- [EF data context](https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.Infrastructure/Persistence/NimboWmsDbContext.cs): `Nimbo.Wms.Infrastructure/Persistence/NimboWmsDbContext.cs`
- **PostgreSQL**
- [Outbox processor](https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.OutboxProcessor/OutboxBackgroundService.cs): `Nimbo.Wms.OutboxProcessor/OutboxBackgroundService.cs`
- [Service defaults](https://github.com/therealmoronto/nimbo-wms/blob/main/Nimbo.Wms.ServiceDefaults/Extensions.cs): `Nimbo.Wms.ServiceDefaults/Extensions.cs`

### Other components

- **WMS user**

## Connections

- WMS user → HTTP API: uses (evidence: `README.md`)
- HTTP API → Request contracts: accepts requests (evidence: `Nimbo.Wms/Controllers/MasterData/ItemsController.cs`)
- HTTP API → Request contracts: routes topology (evidence: `Nimbo.Wms/Controllers/Topology/WarehousesController.cs`)
- HTTP API → WMS documents: dispatches commands
- Request contracts → Master data: dispatches queries
- Request contracts → Warehouse topology: dispatches queries (evidence: `Nimbo.Wms.Infrastructure/UseCases/Topology/Handlers/GetWarehouseTopologyQueryHandler.cs`)
- Request contracts → WMS documents: dispatches documents
- Master data → Master entities: manages (evidence: `Nimbo.Wms.Application/Services/Documents/ReceivingDocumentPostingService.cs`)
- Warehouse topology → EF data context: reads topology (evidence: `Nimbo.Wms.Infrastructure/UseCases/Topology/Handlers/GetWarehouseTopologyQueryHandler.cs`)
- WMS documents → Document aggregates: handles documents (evidence: `Nimbo.Wms.Application/Services/Documents/ReceivingDocumentPostingService.cs`)
- Available lots → EF data context: queries lots (evidence: `Nimbo.Wms.Infrastructure/UseCases/Stock/Handlers/GetAvailableStockLotsQueryHandler.cs`)
- Available lots → Inventory lots: selects stock (evidence: `Nimbo.Wms.Infrastructure/UseCases/Stock/Handlers/GetAvailableStockLotsQueryHandler.cs`)
- Available lots → Quantity rules: maps quantities (evidence: `Nimbo.Wms.Infrastructure/UseCases/Stock/Handlers/GetAvailableStockLotsQueryHandler.cs`)
- Available lots → Typed identifiers: parses IDs (evidence: `Nimbo.Wms.Infrastructure/UseCases/Stock/Handlers/GetAvailableStockLotsQueryHandler.cs`)
- Warehouse topology → DTO mapping: maps results (evidence: `Nimbo.Wms.Infrastructure/UseCases/Topology/Handlers/GetWarehouseTopologyQueryHandler.cs`)
- WMS documents → DTO mapping: maps results
- HTTP API → Result handling: returns results
- Document posting → Stock ledger: records movements (evidence: `README.md`)
- Document posting → Inventory lots: updates stock (evidence: `README.md`)
- Document aggregates → Stock ledger: posts stock changes (evidence: `README.md`)
- EF data context → PostgreSQL: persists data (evidence: `README.md`)
- EF data context → Outbox processor: supplies event data (evidence: `Nimbo.Wms.OutboxProcessor/Program.cs`)
- HTTP API → Service defaults: configures defaults (evidence: `Nimbo.Wms/Controllers/MasterData/ItemsController.cs`)
