mcp-wms-wiki/wiki/architecture/overview.md

---
title: "System Architecture Overview"
type: architecture
sources:
  - areas/architecture/index.md (404 - compiled from cross-source knowledge)
  - areas/saas/index.md (404)
  - areas/hardware/index.md (404)
  - areas/license/index.md (404)
  - areas/ERP.md
  - areas/parameters.md
  - CLAUDE.md context
  - custom/analyse_fonctionnelle.md
  - sources/archives/Presentation_GALILEO.md
  - sources/archives/Communication_WMS_GALILEO.md
related:
  - architecture/security.md
  - architecture/application-dictionary.md
  - architecture/entities-map.md
  - architecture/galileo-integration.md
  - concepts/erp-interface.md
  - concepts/mechanical-elements.md
last_compiled: "2026-04-17"
---

# System Architecture Overview

## Overview

Easy WMS is a Warehouse Management System developed by Mecalux. It is a multi-layer web application running on Windows servers (IIS), backed by a relational database (Oracle, SQL Server, MySQL, or PostgreSQL), accessed via a SmartUI web interface, RF terminals (RFT), and mobile apps.

The system follows an **Application Dictionary (AD)** architecture where most business logic is defined as configurable metadata (entities, commands, workflows) rather than hardcoded logic, enabling extensive customization without code changes.

Easy WMS is available in two deployment models:
- **SaaS (cloud-hosted by Mecalux)**: Multi-tenant, managed infrastructure, Amazon SaaS environment (required for some modules like Amazon Marketplace)
- **On-Premise**: Installed on customer or partner-managed Windows VMs; customer controls updates, backup, and networking

## Deployment Stack

### On-Premise Deployment

| Layer | Technology |
|-------|-----------|
| OS | Windows Server |
| Web Server | IIS (Internet Information Services) |
| Application Runtime | ASP.NET Core (ASPNETCORE_ENVIRONMENT variable for dev/prod) |
| Database | Oracle 19c / SQL Server 2019 / MySQL 8.0.14+ / PostgreSQL 14+ |
| Cache | Redis (session and application cache) |
| Message Queue | Internal background job system (no external broker documented) |
| Equipment Integration | TCP/IP sockets for AGV/PLC, WIFI for Pallet Shuttle tablets |
| Print Server | Local or network label printers (Zebra-type) |

### Application Pools (IIS)

Easy WMS uses multiple IIS application pools to isolate services:
- **Main WMS pool**: Core WMS logic, UI, API endpoints
- **Background Jobs pool**: Asynchronous processing (replenishment, defragmentation, AGV, label prints)
- **Integration pool**: ERP message processing (inbound/outbound queue)

Each pool runs as a separate Windows process with its own identity and recycling schedule.

### SaaS Deployment

In SaaS mode, Mecalux hosts all infrastructure. Key differences:
- Customer accesses via browser only; no local server management
- Updates are applied by Mecalux on a managed schedule
- Some integrations (ERP, label printers, RF equipment) require VPN tunnels or local agents
- Amazon SaaS is a specific certification required for Amazon Marketplace connector (Android 10 device requirement applies)

## API Architecture

Easy WMS exposes three REST API families:

### Application Dictionary API (AD API)
The primary programmatic interface. All AD elements (Commands, Queries, Dialogs, Views, Entities) are accessible via:

```
POST /api/commands/{commandName}       → Execute a Command
GET  /api/queries/{queryName}          → Execute a Query (LINQ-based)
GET  /api/entities/{entityName}        → CRUD on an Entity
POST /api/dialogs/{dialogName}/steps   → Advance a Dialog flow
```

### QueryExecute (LINQ API)
Allows dynamic data retrieval using LINQ-style expressions against any exposed View or Entity. Used for reporting, dashboards, and integration reads.

### CommandExecute API
Used to trigger business operations (receive stock, release orders, assign tasks, etc.) mapped to AD Commands.

### ERP Integration API
Asynchronous message exchange via structured XML/JSON messages over REST or file-based queues. See [ERP Interface](../concepts/erp-interface.md) for the full message catalog.

## Multi-Site and Multi-Warehouse

- A single EasyWMS installation can manage multiple **Sites** (physical warehouses)
- Each site has its own **parameters**, **locations**, **users**, and **equipment**
- Inter-site transfers are managed via transfer orders (SOR type = Transfer)
- The **DOM module** extends this to multi-node distributed order management

## Warehouse Types

Two fundamental warehouse types drive most architectural decisions:

| Type | Description | Key Constraint |
|------|-------------|----------------|
| **Manual warehouse** | Human operators pick using RF or paper; locations accessed directly | No location sequencing required |
| **Automatic warehouse** | Conveyor/shuttle/AGV system; WMS controls machine movements via control system | All movements must go through task queue; no direct access |

Mixed warehouses (some automatic aisles, some manual) are supported. The warehouse type determines which task flows, counting modes, defragmentation strategies, and station types are available.

### Automation control system (TMS)

Automatic warehouses depend on a **Transport Management System (TMS)** that physically drives conveyors, stacker cranes, miniloads, shuttles and lifts. In Mecalux installations the TMS is **GALILEO** (production) or **EasyS** (3D simulation for development / demos). Both dialog with EasyWMS through the **EasyWMS Gateway** Windows service over TCP port 3000.

Principle: **EasyWMS holds all business intelligence** (stock, strategies, orders); **GALILEO has no predictive vision** - it only requests orders and executes them. Three GALILEO-initiated message types drive the flow (Event / Search / End) plus two status update streams (station / route).

Full protocol, workflows (`Galileo_PIEEventHandler_PR`, `Galileo_SearchCreatedEventHandler_PR`, `Galileo_EndCreatedEventHandler_PR`) and command catalogue: [GALILEO Integration](galileo-integration.md). Bring-up and simulation: [Galileo Simulation](../operations/galileo-simulation.md). Troubleshooting: [Galileo Troubleshooting](../operations/galileo-troubleshooting.md).

## Background Job System

Easy WMS relies heavily on background jobs for asynchronous processing:

| Job Name | Frequency | Purpose |
|----------|-----------|---------|
| TryToReplenishProductLocations | Continuous | Automatic replenishment of PDL locations |
| Delete_StockStatusJob_PR | Every 15 min | Remove expired stock quality locks |
| AGV communication jobs | Continuous | Phase protocol exchange with AGV controllers |
| PSService | Continuous | Pallet Shuttle tablet communication |
| Continuous Slotting | Configurable | Ongoing slotting recommendations |
| Metric Gatherer | Configurable | Data Analytics KPI collection |
| Cycle Count Generation | Per schedule | Create cycle count batches |
| Defragmentation Planner | Per schedule | Execute defragmentation strategies |

## Hardware Requirements

### On-premise minimum server specifications

| Server role | CPU | RAM | Storage |
|-------------|-----|-----|---------|
| **Database server** | 4-core @ ≥ 3 GHz | 32 GB | 600 GB (data) + 50 GB (OS) |
| **Application server** | 4-core @ ≥ 3 GHz | 32 GB | 200 GB (logs + app) |

Both servers run Windows Server. For small warehouses the DB and App roles can be on the same machine (specifications must still be met).

### Client and peripheral hardware
- **Client (SmartUI)**: Modern web browser (Chrome/Edge); tablet or desktop PC
- **RF Terminals (RFT)**: Dedicated warehouse scanners running Windows CE or Android; connect via WIFI
- **Label Printers**: Zebra-type thermal printers; connected via network or USB
- **Automatic Warehouse**: Requires PLC/control system interface (proprietary per vendor - AGV, Pallet Shuttle, APS3D each use their own protocol)
- **Scales**: PIE stations can have integrated scales for container weight validation
- **Mobile Devices**: Android 10+ required for Amazon SaaS Marketplace integration

### SaaS tiers (Azure-hosted by Mecalux)

EasyWMS SaaS runs on Azure and is available in three subscription tiers:

| Tier | vCPUs | RAM | Max concurrent users | Max orders/day |
|------|-------|-----|---------------------|----------------|
| **Basic** | 2 | 7 GB | 10 | 200 |
| **Standard** | (contact Mecalux) | - | - | - |
| **Advanced** | (contact Mecalux) | - | - | - |

All SaaS tiers: Mecalux manages infrastructure, updates, backup. ERP integration and printers require VPN tunnel or local agents. Some integrations (Amazon Marketplace) require Android 10+ devices.

## License Model

Easy WMS licenses are modular:
- **Base WMS**: Core inbound/outbound/inventory functionality
- **Module licenses**: Each additional module (AGV, Pallet Shuttle, Multi-Carrier, Slotting, LMS, 3PL Billing, DOM, etc.) requires a separate license
- **User licenses**: Typically per concurrent user or per named user
- **Site licenses**: Some modules require per-site activation

## Parameters and Configuration

System behavior is governed by two layers of parameters:
1. **Organization-level parameters**: Apply globally across all warehouses
2. **Warehouse-level parameters**: Override organization defaults for a specific site

Key system parameters are documented at `areas/parameters.md`. Each functional module has its own parameter set. See [Parameters](../concepts/parameters.md) for the full compiled reference.

## Common Errors

| Symptom | Likely Cause |
|---------|-------------|
| IIS application pool stopped | Background job crash or unhandled exception; check Windows Event Log |
| ERP messages not processed | Integration pool stopped or message queue backlog; check integration logs |
| RF terminal cannot connect | WIFI network issue or IIS binding misconfiguration |
| "Development environment" error in browser | ASPNETCORE_ENVIRONMENT set to Development in production; should be Production |
| Automatic warehouse tasks not generating | Background job (replenishment/defragmentation planner) not running |

## Related

- [Application Dictionary](application-dictionary.md) - AD structure: Commands, Queries, Entities, Workflows
- [Security](security.md) - User roles, authentication, audit
- [Entities Map](entities-map.md) - Data model and entity relationships
- [ERP Interface](../concepts/erp-interface.md) - All ERP messages and integration protocols
- [Parameters](../concepts/parameters.md) - System configuration parameters
- [AGV](../modules/agv.md) - Automatic warehouse AGV protocol
- [Pallet Shuttle](../modules/pallet-shuttle.md) - PS system architecture
- [APS3D](../modules/aps3d.md) - Fleet Manager controller