Locations and Bins: Warehouse Layout in Dragon Guard

Dragon Guard organizes physical warehouse space in a two-level hierarchy: Locations represent distinct warehouses or warehouse zones, and Bins are individual storage slots within a location. Every stock movement, receipt, shipment, and inventory query resolves to a specific (CompanyId, LocationId, BinId) triple, ensuring multi-tenant isolation and precise stock traceability.

The Location → Bin Hierarchy

Tenant (CompanyId)
 └── Location  (e.g. MAIN, LC-GM-01, BODEGA-A)
      └── Bin  (e.g. A-01-01, RECEIVING, DISPATCH)

Rules:

Every Location belongs to exactly one CompanyId.
Every Bin belongs to exactly one CompanyId and exactly one LocationId.
Bin codes are unique within a (CompanyId, LocationId) pair but not globally — the same code such as DEFAULT can exist in multiple locations.
Default location and bin are designated by IsDefault = true on the respective rows, not by a magic code.

The legacy MAIN location code is fully supported for historical tenants, but it is not architecturally required. Any valid tenant-specific location code works identically everywhere in the system.

Locations

List warehouse locations

GET /api/locations

activeOnly

boolean

default:"false"

Return only active locations.

receivingOnly

boolean

default:"false"

Return only locations where allowReceiving = true.

string

Free-text match on code, name, or city.

pageNumber

integer

default:"1"

Page number.

pageSize

integer

default:"20"

Records per page.

Response PagedResponse<LocationDto>

data[].id

uuid

Location UUID.

data[].code

string

Location code (the business key used in receipts, shipments, and integrations).

data[].name

string

Display name.

data[].address

string

Street address line 1.

data[].address2

string

Street address line 2.

data[].city

string

City.

data[].state

string

State or province.

data[].country

string

Country code.

data[].postalCode

string

Postal/ZIP code.

data[].contactName

string

Contact person at this location.

data[].phone

string

Phone number.

data[].email

string

Email address.

data[].isActive

boolean

Active flag.

data[].allowReceiving

boolean

Whether this location accepts inbound receipts.

data[].notes

string

Free-text notes.

Location configuration packages

Locations can be bulk-managed via Excel packages using the same WMS_CONFIG_PACKAGE_V1 format used by items and movements.

Export

GET /api/locations/export-config

Downloads locations_config_package.xlsx with all current locations.

Preview

POST /api/locations/preview-config
Content-Type: multipart/form-data

Returns CREATE/UPDATE preview and validation errors.

Apply

POST /api/locations/apply-config
Content-Type: multipart/form-data

Applies the validated package.

Package columns: Code, Name, Address, Address2, City, State, Country, PostalCode, ContactName, Phone, Email, IsActive, AllowReceiving, Notes.

Bins

Bins represent the physical storage slots within a location. They carry operational attributes that control how warehouse flows interact with them.

List bins

GET /api/bins

companyId

uuid

Override company. Resolved from JWT when omitted.

activeOnly

boolean

default:"true"

Return only active bins.

pageNumber

integer

default:"1"

Page number.

pageSize

integer

default:"20"

Records per page.

Response PagedResponse<BinDto>

data[].id

uuid

Bin UUID.

data[].binCode

string

Bin code. Unique within (CompanyId, LocationId).

data[].description

string

Bin description.

data[].isActive

boolean

Active flag.

data[].isBlocked

boolean

Whether the bin is currently blocked from operational use.

data[].isDefault

boolean

Whether this is the default bin for its location.

data[].binType

string

Type classification (e.g. STORAGE, RECEIVING, DISPATCH).

data[].allowPicking

boolean

Whether stock can be picked from this bin.

data[].allowPutaway

boolean

Whether stock can be put away into this bin.

data[].companyId

uuid

Owning company UUID.

Get bin detail

GET /api/bins/{id}

Returns a BinDetailDto which extends BinDto with location context:

companyName

string

Owning company display name.

createdAt

datetime

Creation timestamp.

updatedAt

datetime

Last modification timestamp.

The GET /api/bins/{id} endpoint accepts requests from any company in the caller’s accessible company list (as determined by the JWT), not just the primary CompanyId. This supports multi-company admin scenarios.

Bin Consistency Model

Bins are soft-unique per (CompanyId, LocationId). The same binCode string (e.g. DEFAULT) may exist in multiple locations of the same tenant with independent operational attributes. All bin resolution in receiving, shipment, movement, and stock queries must include both CompanyId and LocationId context. Default resolution order used by all modules when an explicit bin is not provided:

Caller-supplied binId (highest precedence).
Active tenant default bin for the target location (IsDefault = true).
Legacy compatibility fallback for historical rows with blank binId (read-only display only).

Do not assume DEFAULT BIN or any specific bin code as the system default. Default bins are identified by IsDefault = true on the bin row, not by their code value.

Operational attribute rules:

Attribute	Enforced by
`isBlocked = true`	Receiving line update rejects the bin for putaway.
`allowPutaway = false`	Receiving line update rejects the bin for putaway.
`allowPicking = false`	Future pick validation will reject the bin for picking.

MAIN Location / MAIN Bin Convention

When a new tenant is bootstrapped, Dragon Guard seeds a default location and a default bin. Bootstrap inputs may supply custom codes; if omitted, the system may create a location using the MAIN code as a compatibility default. Key rules:

MAIN is legacy-compatible but not mandatory. Any location code the tenant provides during setup is equally valid everywhere in the system.
Existing tenants using MAIN are not affected. All operational flows (receipts, shipments, movements, handheld) check IsDefault on the database row, not the code string.
New integrations should use the tenant’s real location code (obtained from GET /api/locations?activeOnly=true) rather than hardcoding MAIN.

Warehouse Setup

The warehouse setup controller provides CRUD operations for locations and bins without the Excel package ceremony.

GET  /api/warehouse/locations
GET  /api/warehouse/locations/{id}
POST /api/warehouse/locations
PUT  /api/warehouse/locations/{id}
PUT  /api/warehouse/locations/{id}/activate
PUT  /api/warehouse/locations/{id}/deactivate
PUT  /api/warehouse/locations/{id}/default

GET  /api/warehouse/locations/{locationId}/bins
POST /api/warehouse/locations/{locationId}/bins
PUT  /api/warehouse/bins/{id}
PUT  /api/warehouse/bins/{id}/activate
PUT  /api/warehouse/bins/{id}/deactivate
PUT  /api/warehouse/bins/{id}/default

GET /api/warehouse/setup-status

Returns whether the tenant has completed minimum warehouse setup (at least one active location with at least one active bin).

For multi-location tenants, use POST /api/locations/apply-config with an Excel location package to bulk-create all locations in a single operation rather than creating them individually through the warehouse setup flow.

Document Sequences

Dragon Guard uses auto-incrementing document number sequences for all transactional documents. These sequences are company-scoped and self-healing — when a sequence row is missing for a tenant (common for older tenants), the relevant endpoint creates it automatically.

GET /api/document-sequence

Returns the list of all document sequence configurations for the active company.

`documentType`	Format	Used by
`ITEM_CREATED`	`ITM-NNNNNN`	Item creation
`RECEIPT_CREATED`	`RCP-NNNNNNN`	Receiving header creation
`POSTED_RECEIVE`	`PR-NNNNNN`	Receiving post
`PURCHASE_ORDER`	`PO-NNNNNN`	Auto-generated PO numbers
`SHIPMENT_CREATE`	`SHP-NNNNNN`	Shipment creation
`POSTED_SHIPMENT`	`PS-NNNNNN`	Shipment post
`SALES_ORDER`	`SO-NNNNN`	Auto-generated SO numbers
`INVENTORY_RECOUNT`	`RC-NNNNNNN`	Inventory recount creation

You can inspect the current lastNumber for any sequence type to understand the numbering state of your tenant. Sequence rows are never deleted; they accumulate over the lifetime of the tenant.

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Locations and Bins: Warehouse Layout in Dragon Guard

The Location → Bin Hierarchy

Locations

List warehouse locations

Location configuration packages

Export

Preview

Apply

Bins

List bins

Get bin detail

Bin Consistency Model

MAIN Location / MAIN Bin Convention

Warehouse Setup

Document Sequences

Build docs developers (and LLMs) love

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Documentation Index

​The Location → Bin Hierarchy

​Locations

​List warehouse locations

​Location configuration packages

Export

Preview

Apply

​Bins

​List bins

​Get bin detail

​Bin Consistency Model

​MAIN Location / MAIN Bin Convention

​Warehouse Setup

​Document Sequences

Build docs developers (and LLMs) love

The Location → Bin Hierarchy

Locations

List warehouse locations

Location configuration packages

Bins

List bins

Get bin detail

Bin Consistency Model

MAIN Location / MAIN Bin Convention

Warehouse Setup

Document Sequences