\n\n

EWM + AI Hive — Documentation

A self-contained SAP Extended Warehouse Management simulation, a SQLite-backed integration layer, and a Fiori-style UI — designed so external AI orchestrators (Dify, n8n, custom agents) can pull warehouse data and reason over it.

\n\n

\n Three components. Each runs on Val Town and is independently deployed:\n \n \n \n \n \n \n \n

Val	Role	URL
`ewmMockServer`	Generates realistic SAP EWM data on the fly	`${MOCK}`
`ewmBackend`	Hono + SQLite. Seeds and serves all data + chunking	`${BACKEND}`
`ewmDashboard`	OpenUI5 Fiori frontend	`${FRONTEND}`

\n\n

How it maps to a real SAP landscape

\n \n \n \n \n \n \n \n \n \n

Real SAP	This project
SAP S/4HANA system (ABAP + HANA DB)	`ewmBackend` (Hono + Val Town SQLite)
SAP EWM transactional data (RPA, AAR, etc.)	`ewmMockServer` generates the same shapes
SAP Fiori Launchpad / NetWeaver Gateway	`ewmDashboard` (OpenUI5 + Horizon theme)
SAP Integration Suite / CPI	Direct REST calls from Dify / external orchestrator
SAP Build Process Automation	Dify workflow that reads `/api/chunks`

\n\n

Quickstart

Open the Dashboard
Click Data Management in the side navigation
Click Seed master data — populates the plants + warehouses SQLite tables (15 warehouses, 5 plants)
Pick an Entity + Warehouse + Record limit, click Seed — pulls records from the mock and stores them in entity_records
Click Warehouse Monitor to browse the data
Click AI Chunking Lab, pick a strategy, run an ingest — produces chunks ready for Dify
Point your Dify workflow at GET ${BACKEND}/api/chunks?run_id=...&payload=1

\n\n

Architecture

Data flows in one direction: mock generates → backend seeds + chunks → frontend reads + AI consumer reads.

\n ┌──────────────────────┐\n │ ewmMockServer │\n │ (Hono · Val Town) │ ← generates SAP EWM data on demand\n │ │ ~11.5M virtual records\n │ /api/ewm/<entity> │\n │ /api/ewm/warehouses│\n └──────────┬───────────┘\n │ X-API-Key\n ▼\n ┌──────────────────────┐ ┌────────────────────┐\n │ ewmBackend │ ─────► │ Val Town SQLite │\n │ (Hono · SQLite) │ ◄───── │ │\n │ │ │ plants │\n │ POST /api/seed │ │ warehouses │\n │ GET /api/data │ │ entity_records │\n │ POST /api/ingest │ │ chunks │\n │ GET /api/chunks │ │ ingest_runs │\n │ │ │ seed_runs │\n └──────┬─────────┬─────┘ └────────────────────┘\n │ │\n ┌─────▼───┐ ┌──▼──────────────┐\n │ Fiori │ │ Dify Workflow │\n │ Dashbd │ │ (AI Hive) │\n │ (UI5) │ │ reads chunks │\n └─────────┘ └─────────────────┘\n

\n\n

SAP EWM Concepts (Refresher)

Entities exposed by this system map 1:1 to SAP S/4HANA EWM tables.

Plant

Top-level organisational unit (e.g. PL01 — Singapore Manufacturing Hub).

Warehouse

A physical site under a plant (e.g. PL01-WH1). Has Zones (GR/GI/LS/QI/HZ).

Warehouse Order (WO)

The smallest unit of work. Contains tasks like Pick / Putaway / Count.

Transfer Order (TO)

Move stock between locations within a warehouse.

Stock Position

Where in the warehouse a material currently sits (bin × batch × HU).

Inbound Delivery (IBD)

Goods arriving from a vendor.

Outbound Delivery (OBD)

Goods leaving to a customer.

Wave

A batch of outbound deliveries grouped for picking efficiency. Contains many Picking Tasks.

Handling Unit (HU)

Physical container (pallet, carton) bundling materials together.

\n\n

Data Model (SQLite)

All persistent state lives in Val Town SQLite, managed by ewmBackend.

\n\n

Master data

plants

\n \n \n \n \n \n \n \n \n \n \n \n

Column	Type	Notes
`id`	TEXT PK	e.g. `PL01`
`name`	TEXT	Plant display name
`country`	TEXT	ISO 2-letter
`region`	TEXT	APAC / EMEA / AMER
`currency`	TEXT	ISO 3-letter
`data`	TEXT (JSON)	Full record
`updated_at`	TEXT	ISO datetime

\n\n

warehouses

\n \n \n \n \n \n \n \n \n \n \n \n

Column	Type	Notes
`id`	TEXT PK	e.g. `PL01-WH1`
`plant_id`	TEXT	FK to plants
`plant_name`	TEXT	Denormalised
`type`	TEXT	Manufacturing / Distribution / Returns/Repair
`country`	TEXT
`region`	TEXT
`data`	TEXT (JSON)	Full record incl. zones array

\n\n

Transactional data

entity_records

Generic table holding all transactional entity rows. Each row is one warehouse document.

\n \n \n \n \n \n \n \n \n \n \n \n

Column	Type	Notes
`(entity, record_id)`	PK	Composite
`entity`	TEXT	WarehouseOrders / TransferOrders / ...
`record_id`	TEXT	e.g. `WO-PL01-WH1-0000001`
`warehouse_id`	TEXT	Indexed
`plant_id`	TEXT
`status`	TEXT	Open / In Progress / Done / Cancelled. Indexed.
`data`	TEXT (JSON)	Full record

Indexes: (entity, warehouse_id), (entity, status).

\n\n

AI chunking

ingest_runs

One row per chunking operation triggered from the Chunking Lab.

\n \n \n \n \n \n \n \n \n \n \n \n \n

Column	Notes
`run_id` PK	UUID
`entity`	Source entity
`strategy`	per-record / group-warehouse / token-budget / field-window
`warehouse_id`	Filter, nullable
`token_budget` / `field_window` / `record_limit`	Strategy params
`status`	running / done / failed
`total_chunks` / `total_records` / `total_tokens`	Aggregates
`started_at` / `finished_at` / `error`

\n\n

chunks

\n \n \n \n \n \n \n \n \n \n

Column	Notes
`id` PK	Autoincrement
`run_id`	FK to ingest_runs
`chunk_index`	Position within the run
`record_count` / `tokens`	For LLM budgeting
`payload`	JSON string ready to ship to Dify

\n\n

seed_runs

Audit log of every POST /api/seed invocation. Useful for monitoring and replay.

\n\n

API Reference

All endpoints are served by ewmBackend at ${BACKEND}. CORS is open; no auth required (the backend handles the X-API-Key handshake with the mock internally).

\n\n

Health & Metadata

\n\n

GET/api/health

Liveness probe.

curl ${BACKEND}/api/health\n{ \"ok\": true, \"mock\": \"https://...\" }

\n\n

GET/api/entities

Lists supported entity names and chunking strategies.

{\n  \"entities\": [\"WarehouseOrders\",\"TransferOrders\",\"StockPositions\",\n               \"InboundDeliveries\",\"OutboundDeliveries\",\"Waves\"],\n  \"strategies\": [\"per-record\",\"group-warehouse\",\"token-budget\",\"field-window\"]\n}

\n\n

Master Data

\n\n

GET/api/warehouses

All warehouses from SQLite (after seeding). Shape mirrors OData.

{\n  \"@odata.count\": 15,\n  \"value\": [\n    { \"id\": \"PL01-WH1\", \"plantId\": \"PL01\", \"plantName\": \"Singapore...\",\n      \"country\": \"SG\", \"type\": \"Manufacturing\", \"zones\": [...] }, ...\n  ]\n}

\n\n

POST/api/seed/master

Pulls all plants + warehouses from the mock into SQLite. Idempotent — re-running overwrites.

curl -X POST ${BACKEND}/api/seed/master -d '{}'\n{ \"ok\": true, \"plants\": 5, \"warehouses\": 15 }

\n\n

Transactional Data

\n\n

POST/api/seed

Seeds records of one entity into entity_records. Use warehouseId to scope.

Request body

\n \n \n \n \n

`entity`	required, one of the entity names
`warehouseId`	optional, filters source query
`limit`	1–100000, default 1000

curl -X POST ${BACKEND}/api/seed \\\\\n  -H \"Content-Type: application/json\" \\\\\n  -d '{\"entity\":\"WarehouseOrders\",\"warehouseId\":\"PL01-WH1\",\"limit\":1000}'\n\n{ \"ok\": true, \"entity\": \"WarehouseOrders\", \"warehouseId\": \"PL01-WH1\",\n  \"inserted\": 1000, \"seedId\": \"12\" }

\n\n

GET/api/data/:entity

Paginated SQLite read. OData-shaped response.

Query params

\n \n \n \n \n

`warehouseId`	optional filter
`$top`	page size, max 500, default 25
`$skip`	offset, default 0

curl \"${BACKEND}/api/data/WarehouseOrders?warehouseId=PL01-WH1&$top=10\"\n{\n  \"@odata.context\": \"$metadata#WarehouseOrders\",\n  \"@odata.count\": 1000,\n  \"value\": [ { \"WarehouseOrderID\": \"WO-PL01-WH1-0000001\", ... }, ... ]\n}

\n\n

GET/api/seed/stats

Per-entity row counts, master data counts, recent seed run history.

{\n  \"byEntity\": [ { \"entity\": \"WarehouseOrders\", \"n\": 1000, \"latest\": \"...\" }, ... ],\n  \"warehouses\": 15,\n  \"plants\": 5,\n  \"runs\": [ { \"id\": 1, \"entity\": \"...\", \"inserted\": 50, \"status\": \"done\", ... } ]\n}

\n\n

AI Chunking

\n\n

POST/api/ingest

Read seeded data from SQLite, apply chunking strategy, persist to chunks.

Request body

\n \n \n \n \n \n \n \n

`entity`	required
`strategy`	required, see strategies
`warehouseId`	optional filter
`limit`	max records to chunk, default 1000
`tokenBudget`	for token-budget strategy, default 2000
`windowSize`	for field-window strategy, default 50

curl -X POST ${BACKEND}/api/ingest \\\\\n  -H \"Content-Type: application/json\" \\\\\n  -d '{\"entity\":\"WarehouseOrders\",\"strategy\":\"token-budget\",\"limit\":500,\"tokenBudget\":2000}'\n\n{ \"run\": { \"run_id\": \"8d67...\", \"total_chunks\": 17, \"total_tokens\": 12918, ... } }

\n\n

GET/api/chunks

Lists chunks. Filterable; supply payload=1 to include the JSON payload (large).

Query params

\n \n \n \n \n \n

`run_id`	filter to one run
`entity` / `strategy`	filters
`payload`	\"1\" to include the `payload` column
`limit` / `offset`	pagination

\n\n

GET/api/chunks/:id

Single chunk including full payload.

\n\n

GET/api/runs

Ingest run history.

\n\n

DELETE/api/runs/:id

Deletes a run and all its chunks.

\n\n

GET/api/stats

Aggregate stats: totals, per-entity, per-strategy, per-status.

\n\n

Chunking Strategies

All four strategies emit chunks of the form { entity, records: [...] } or a variant. Tokens are estimated as ceil(JSON.stringify(record).length / 4) — close enough for budgeting LLM context.

\n\n

per-record

One record per chunk. Maximum granularity. Best when each document is an independent fact (e.g. a single warehouse order).

\n Output: N records → N chunks. Average chunk ≈ 200 tokens for WarehouseOrders.
\n Use when: embedding each record into a vector store, RAG over individual documents.\n

\n\n

group-warehouse

All records sharing a warehouse_id become one chunk.

\n Output: N records → ≤15 chunks (one per warehouse).
\n Use when: per-warehouse summaries, location-scoped agents.\n

\n\n

token-budget

Greedy packer: accumulates records into a chunk until adding the next would exceed tokenBudget, then starts a new chunk.

\n Output: Each chunk ≤ tokenBudget tokens.
\n Use when: filling an LLM context window without truncating mid-record.\n

\n\n

field-window

For records with large nested arrays (e.g. Waves with hundreds of picking tasks): splits the array into windows of windowSize, each window emitted as a chunk that includes the parent record metadata.

\n Output: 1 Wave with 100 picking tasks → 100/windowSize chunks, all linked to the same parent.
\n Use when: a single record is too large for the model's context.\n

\n\n

Dify Workflow Integration

Dify is an LLM orchestration platform. This section shows how to wire a Dify workflow to consume EWM data via the ewmBackend REST API.

\n\n

Pattern 1 — Retrieval over chunks (RAG-style)

In the dashboard's Data Management page, seed the entities you care about (e.g. WarehouseOrders for one warehouse).
In AI Chunking Lab, pick a strategy. token-budget with budget=2000 is a good default.
Note the run_id.

In Dify, add an HTTP Request node:\n

GET ${BACKEND}/api/chunks?run_id={{run_id}}&payload=1&limit=500\nHeaders: (none)

Add an Iteration node to loop over response.chunks[*].
Inside the loop, pass item.payload as context to an LLM node.
Aggregate results with a Code or Template node.

\n\n

Pattern 2 — Live entity query (no chunking)

When the agent needs to look up specific records ad-hoc.

In Dify, add an HTTP Request tool that exposes a parameter warehouseId:\n

GET ${BACKEND}/api/data/WarehouseOrders?warehouseId={{warehouseId}}&$top=50

Use it as a tool the LLM can call (\"function calling\").
The LLM emits a warehouseId, Dify hits the endpoint, returns up to 50 orders.

\n\n

Pattern 3 — Trigger chunking on demand

Let the workflow itself chunk fresh data each run.

POST ${BACKEND}/api/ingest\nBody: {\n  \"entity\": \"OutboundDeliveries\",\n  \"strategy\": \"token-budget\",\n  \"warehouseId\": \"PL01-WH1\",\n  \"limit\": 1000,\n  \"tokenBudget\": 2000\n}\nResponse: { \"run\": { \"run_id\": \"...\", \"total_chunks\": 47, ... } }

Then fetch chunks with the returned run_id.

\n\n

Authentication

\n Production note. The backend currently has no auth on its own endpoints; only the underlying mock requires X-API-Key (handled internally). For production, put a reverse proxy / Cloudflare Worker in front of ewmBackend and check a token on every request.\n

\n\n

Example Flows

\n\n

\"Summarise today's open orders for PL01-WH1\"

1. POST /api/seed       { entity: \"WarehouseOrders\", warehouseId: \"PL01-WH1\", limit: 1000 }\n2. POST /api/ingest     { entity: \"WarehouseOrders\", strategy: \"group-warehouse\",\n                          warehouseId: \"PL01-WH1\", limit: 1000 }\n3. GET  /api/chunks?run_id=&payload=1\n4. LLM: \"Summarise the following warehouse orders, grouping by status...\" + chunk.payload

\n\n

\"Find the wave with the most overdue picking tasks\"

1. POST /api/seed       { entity: \"Waves\", warehouseId: \"PL01-WH1\", limit: 200 }\n2. POST /api/ingest     { entity: \"Waves\", strategy: \"field-window\",\n                          warehouseId: \"PL01-WH1\", limit: 200, windowSize: 25 }\n3. GET  /api/chunks?run_id=...&payload=1\n4. LLM scans each chunk for overdue PickingTasks, aggregates by WaveID

\n\n

\"Lookup specific delivery\"

GET /api/data/OutboundDeliveries?warehouseId=PL01-WH1&$top=500\n→ filter client-side by OutboundDeliveryID

\n\n

Troubleshooting

\n\n

Browse shows \"0 total, showing 0\"

SQLite is empty for that entity. Go to Data Management and seed it first.

\n\n

Ingest returns \"Unauthorized\"

The API_KEY env var on ewmBackend doesn't match the one on ewmMockServer. Open both vals' env var pages on Val Town and set them to the same value (default ewm-demo-key-aihive-2025).

\n\n

Seed hits 30s timeout

Val Town caps each request at 30s. Reduce limit (≤2000 typically completes), or seed one warehouse at a time using warehouseId.

\n\n

Chunks table is empty after ingest

Did you seed the source entity first? Chunking reads from entity_records. An empty source produces zero chunks.

\n\n

UI says \"Loading...\" forever

Open browser DevTools → Network. If ${BACKEND} is not reachable, the backend val may be down or the URL may have changed. Update BACKEND in the dashboard val source.

\n\n \n\n

Branches1

Branches
1