mcp-wms-wiki/wiki/architecture/application-dictionary.md

---
title: "Application Dictionary (AD)"
type: architecture
sources:
  - CLAUDE.md context (AD API knowledge)
  - areas/ERP.md
  - areas/TransactionTypes.md
  - Cross-source knowledge from all batches
related:
  - architecture/overview.md
  - architecture/entities-map.md
  - concepts/erp-interface.md
  - concepts/transactions.md
last_compiled: "2026-04-10"
---

# Application Dictionary (AD)

## Overview

The **Application Dictionary (AD)** is the core metadata framework of Easy WMS. Rather than hardcoding business logic, the system defines all operations, data structures, and UI elements as configurable AD elements stored in the database. This makes Easy WMS highly customizable: partners and customers can extend or modify behavior without touching application code.

The AD contains approximately **38,765 elements** spanning Commands, Queries, Dialogs, Views, Entities, Events, Workflows, and more. Every UI action, every RF terminal screen, and every API call is backed by one or more AD elements.

## AD Element Types

### Commands

Commands represent **executable operations** - actions that change system state.

- Mapped to `POST /api/commands/{commandName}` in the API
- Have input parameters (validated before execution) and return a result
- May trigger Transactions (audit records) and Events
- May invoke sub-commands or start Workflows
- Examples:
  - `ReceiveContainer` - receive a container at a dock station
  - `ReleaseShippingOrder` - release a shipping order for picking
  - `AdjustStock` - perform a quantity adjustment
  - `CreateCount` - create a physical count order
  - `AssignTask` - assign a task to an operator

Commands are permission-controlled: each command is associated with one or more AD roles. A user can only execute commands their role permits.

### Queries

Queries represent **data retrieval operations** using a LINQ-style expression engine.

- Mapped to `GET /api/queries/{queryName}` or `POST /api/queries/execute` (dynamic)
- Support filtering, sorting, pagination
- Can reference any View or Entity
- Examples:
  - `GetStockByLocation` - fetch stock for a location
  - `GetOpenShippingOrders` - fetch all non-closed shipping orders
  - `GetContainerContents` - fetch stock lines in a container
  - `GetTasksByStatus` - fetch tasks matching a status

The **QueryExecute API** allows ad-hoc LINQ queries without pre-defining a named Query element.

### Entities

Entities are the **core data objects** of the system - the persistent domain model.

Each Entity has:
- A schema (fields, types, constraints)
- CRUD operations accessible via `GET/POST/PUT/DELETE /api/entities/{entityName}`
- Relations to other Entities
- Business rules enforced on create/update/delete

Key Entities (from all compiled batches):

| Entity | Description |
|--------|-------------|
| `Container` | LPN with type, weight, status, lock, location |
| `Location` | Physical or virtual storage position |
| `Stock` | Stock line: item + qty + UoM + logistic attributes + container + location |
| `Item` (Product) | SKU master with types, families, UoM, profiles |
| `ReceiptOrder` | Inbound order (supplier/return/transfer) |
| `Receipt` | Physical receiving event linked to receipt orders |
| `ShippingOrder` | Outbound order (customer/transfer/return) |
| `Task` | Movement task with type, origin, destination, status |
| `Count` | Inventory count order with lines and status |
| `Route` | Carrier route with loads and departure schedule |
| `Load` | Truck load linked to a route |
| `Station` | Warehouse station configuration |
| `Owner` | Stock owner (for 3PL multi-tenancy) |
| `Account` | Customer/delivery account |
| `Supplier` | Vendor master |
| `Carrier` | Shipping carrier master |
| `Delivery` | Multi-Carrier delivery (carrier + consignee) |
| `ContainerType` | LPN type definition |
| `ItemType` / `ItemFamily` | Item classification hierarchy |
| `UoM` | Unit of Measure with conversions |
| `Zone` | Storage or working zone |
| `SubWarehouse` | Logical sub-division of warehouse |
| `Equipment` | Warehouse equipment (forklift, RFT, conveyor) |
| `UserStatus` | Stock quality status definition |
| `VASTemplate` | Value Added Services template |
| `Kit` | Kit definition with components |
| `Appointment` | Yard Management appointment |
| `Slot` | Slotting recommendation |
| `LaborActivity` | LMS activity record |
| `BillingContract` | 3PL billing contract |
| `DOMNode` | Distributed Order Management node |

### Views

Views are **read-only projections** of one or more Entities, optimized for display and reporting.

- Accessible via `GET /api/views/{viewName}` or QueryExecute
- Often join multiple entities (e.g., stock + container + location + item)
- May include computed columns and aggregations
- Back all SmartUI list screens and RF terminal display screens
- Examples:
  - `ViewContainers` - containers with location and status
  - `ViewStocks` - stock lines with full context
  - `ViewTasksOpen` - open tasks with assignment info
  - `ViewShippingOrdersMonitor` - order monitoring dashboard
  - `ViewGroupedStock` - aggregated stock by item/owner

### Dialogs

Dialogs are **multi-step interactive flows** that guide an operator through a complex operation.

- Used primarily in RF terminals and workstation screens
- Each Dialog has **steps** (screens), each advancing the flow
- State is maintained server-side between steps
- API: `POST /api/dialogs/{dialogName}/start`, then `POST /api/dialogs/{sessionId}/step`
- Examples:
  - `ReceptionDialog` - multi-step reception flow (select order → scan container → enter quantities → confirm)
  - `PickingDialog` - guided picking (scan location → confirm quantity → scan destination)
  - `CountDialog` - count guided flow (scan location → count items → confirm)
  - `ShippingConsolidationDialog` - consolidation at shipping station

Dialogs encapsulate the complete operator interaction sequence for a process, invoking Commands internally at each confirmation step.

### Events

Events are **system notifications** that fire when certain state transitions occur.

- Triggered automatically by Commands (not by users directly)
- Can invoke Workflows, send notifications (SCEM), or trigger ERP messages
- Examples:
  - `OnShippingOrderClosed` → triggers SOF ERP message + SOC status change notification
  - `OnReceiptOrderStatusChange` → triggers ROC ERP message
  - `OnStockExpired` → fires `EasyWMS_StockExpired` notification event
  - `OnContainerReceived` → triggers ASO ERP message (if ASN container)
  - `OnTaskGenerated` → notifies AGV controller (automatic warehouse)

Events decouple the triggering action from downstream reactions, enabling clean extension without modifying core logic.

### Workflows

Workflows are **orchestrated sequences** of Commands, conditional logic, and state transitions.

- Used for complex multi-step processes: reception, putaway strategy evaluation, replenishment logic
- Can be synchronous (blocking) or asynchronous (background)
- Examples:
  - `PutawayWorkflow` - 8-stage pipeline (criteria → aisles → balancing → restrictions → validity → rules → sort → select)
  - `StockAssignmentWorkflow` - evaluate assignment strategies → assign to shipping order lines
  - `ReplenishmentWorkflow` - check PDL levels → select strategy → generate tasks
  - `DefragmentationWorkflow` - evaluate rotation/shipping criteria → generate movement tasks
  - `CountCloseWorkflow` - close count → compute differences → generate STK.ADJ transactions → send COF to ERP

### Background Jobs

Background Jobs are **scheduled or continuous Workflows** that run autonomously:

| Job | Trigger | Workflow Invoked |
|-----|---------|-----------------|
| `TryToReplenishProductLocations` | Continuous | ReplenishmentWorkflow |
| `Delete_StockStatusJob_PR` | Every 15 min | QualityUnlockWorkflow |
| `CycleCountGenerationJob` | Per schedule | CountGenerationWorkflow |
| `DefragmentationPlannerJob` | Per schedule | DefragmentationWorkflow |
| `SlottingAnalysisJob` | Configurable | SlottingWorkflow |
| `MetricGathererJob` | Configurable | DataAnalyticsWorkflow |
| `AGVCommunicationJob` | Continuous | AGVProtocolWorkflow |
| `PSServiceJob` | Continuous | PalletShuttleWorkflow |

### Parameters

AD Parameters are the **configuration knobs** of the system - named key-value pairs that alter behavior without code changes.

- Scope: Organization or Warehouse
- Accessible via the Parameters view in SmartUI (Inventory > Parameters)
- Read by Commands, Workflows, and Background Jobs at runtime
- See [Parameters](../concepts/parameters.md) for the full compiled catalog

## AD API Access Patterns

### Reading data (QueryExecute)

```http
POST /api/queryexecute
{
  "query": "Stock.Where(s => s.LocationCode == 'A0101' && s.ItemCode == 'SKU001')",
  "site": "WH01"
}
```

### Executing a command

```http
POST /api/commandexecute
{
  "command": "ReleaseShippingOrder",
  "parameters": {
    "ShippingOrderCode": "SO-20260410-001",
    "Site": "WH01"
  }
}
```

### Reading an entity

```http
GET /api/entities/ShippingOrder/SO-20260410-001?site=WH01
```

## AD Element Naming Conventions

Based on patterns observed across documentation:
- **Commands**: PascalCase verb-noun (`ReceiveContainer`, `ReleaseOrder`, `AdjustStock`)
- **Queries**: `Get` + PascalCase noun (`GetStockByLocation`, `GetOpenTasks`)
- **Entities**: PascalCase noun (`Container`, `Stock`, `ShippingOrder`)
- **Views**: `View` + PascalCase noun (`ViewContainers`, `ViewStocks`)
- **Dialogs**: Context + `Dialog` suffix (`ReceptionDialog`, `PickingDialog`)
- **Events**: `On` + PascalCase noun+verb (`OnShippingOrderClosed`)
- **Parameters**: `SCREAMING_SNAKE_CASE` (`MAX_DEFRAG_TASKS`, `ECOMMERCE_RECEPTION_ALLOW_AUTOSELECTION`)
- **Transactions**: `ENTITY.VERB` dot notation (`CON.MOVE`, `STK.ADJ`, `OUT.CLS`)
- **ERP Messages**: 3-letter uppercase code (`SOR`, `ROC`, `STR`)

## Extension Points

The AD can be extended by Mecalux partners:
1. **Custom Commands**: Add new business operations
2. **Custom Views**: Expose new data projections
3. **Custom Workflows**: Override or extend default process logic
4. **Custom Parameters**: Add module-specific configuration
5. **Custom Events**: React to standard system events with custom logic

This extensibility model is used by all optional modules (AGV, Slotting, 3PL Billing, DOM, etc.) - each module adds its own AD elements without modifying core elements.

## Related

- [Overview](overview.md) - System architecture and deployment
- [Entities Map](entities-map.md) - Visual map of entity relationships
- [Transactions](../concepts/transactions.md) - Transaction audit trail (generated by Commands)
- [ERP Interface](../concepts/erp-interface.md) - ERP messages (triggered by Events)
- [Parameters](../concepts/parameters.md) - System parameter catalog