Service domains
jtWMS is split into services along business lines. Each service owns one domain: it is the only place that domain’s data is written, it keeps that data in its own database, and it exposes it through its part of the REST API. No service reads another service’s database, so one service’s data reaches another only through the API or through events.
| Domain | Owns | API routes |
|---|---|---|
| Identity and access | Tenants, users, sign-in, roles and permissions, API keys, plans | /connect/, /api/v1/auth, /api/v1/team, /api/v1/invites, /api/v1/api-keys, /api/v1/tenants, /api/v1/plans |
| Warehouse configuration | Facilities, storage layout, locations, zones, equipment | /api/v1/facilities, /api/v1/snapshot, /api/v1/audit-entries |
| Catalog | Products, units of measure, barcodes, categories | /api/v1/products, /api/v1/product-categories |
| Inventory | Stock positions, the stock ledger, receipts, adjustments, license plates, moves, holds and releases, allocations and picks | /api/v1/facilities/{facilityId}/inventory/ |
| Webhooks | Webhook subscriptions and deliveries | /api/v1/webhook-subscriptions, /api/v1/webhook-deliveries |
Identity and access
Section titled “Identity and access”The identity service is the authority on who a caller is and what they may do.
- Tenants and sign-up. Signing up creates the tenant, its first administrator and a read-only API key.
- Sign-in. It issues the access and refresh tokens users sign in with, and ends sessions when a user’s access changes.
- Users and roles. Invitations, role assignments, custom roles and the standard system roles. Each service that defines permissions registers them here, so roles can be built from them.
- API keys. Keys for machine-to-machine access, each with a scope of permissions.
- Plans. Each tenant’s plan, add-ons, limits and feature modules.
- Password reset. Reset links by email, or issued by an administrator.
See Security model and the Team guide.
Warehouse configuration
Section titled “Warehouse configuration”The warehouse configuration service describes each facility: its physical layout and how it is organised.
- Facilities, with the pattern their location codes follow.
- Storage layout, a tree of areas, aisles, bays, levels and positions. Each position is a location with a capacity and storage type, and its code is derived from its place in the tree.
- Zones, grouped into zone profiles so a facility can keep alternative zone layouts and choose which one is active.
- Equipment, such as conveyors, diverts and scanners, and the connections that show how product flows between them.
- Import and export of a facility’s whole layout as one file, and snapshots that give another system the current configuration in one read.
See the Storage topology and Equipment layout guides.
Catalog
Section titled “Catalog”The catalog service holds the products a tenant stocks: each product’s SKU, its units of measure from the base unit up to larger packs, its barcodes and its category. It supports lookup by barcode or SKU, a bulk create-or-update by SKU that applies a whole batch or none of it, and a snapshot of the full catalog. The catalog is a feature module: a tenant’s plan must include it. See the Products guide.
Inventory
Section titled “Inventory”The inventory service tracks each facility’s stock: how much of each product is at each location, by lot, serial number, expiry date and the day it was received. Every change is recorded in an append-only stock ledger and published as an event. Stock is received into locations and corrected with adjustments that carry a reason (shrinkage, damage, found stock and so on). License plates (pallets, and the cases and totes on them) hold stock and move as one; stock and license plates are moved between locations, and any scanned code (a license plate, a location, a barcode or a SKU) can be looked up with what it holds. Stock can be put on hold, as quarantined or damaged, where it is: still counted, but no longer available, until it is released. Stock is allocated to order lines in the order of each product’s rotation strategy (first in first out, last in first out, or first expired first out), skipping held, blocked and expired stock; allocated stock is picked to a staging location or a tote, where it stays allocated, and an allocation can be released. Stock of a product or at a location that is no longer active is kept and flagged as blocked, and nothing new is put into it. The inventory service keeps its own copies of the catalog’s products and the warehouse configuration’s facilities and locations, updated from their events. Inventory is a feature module: a tenant’s plan must include it. Its routes sit under each facility; today they are API only.
Webhooks
Section titled “Webhooks”The webhooks service turns jtWMS events into signed HTTPS deliveries to your endpoints. It holds each tenant’s subscriptions and a record of every delivery, retries failed deliveries, and keeps those that never succeeded for redelivery. See Webhooks.
The gateway
Section titled “The gateway”The gateway is the single entry point to the API. It owns no business data. For every request it:
- authenticates the caller, with a user access token or an API key;
- removes any identity information the caller supplied, and passes on only what it established from the credentials: the tenant, the user or key, and the permissions;
- refuses routes the tenant’s plan doesn’t include (today, the catalog and inventory routes), and applies the tenant’s rate limits;
- assigns or accepts a correlation ID, and forwards the request to the service that owns the route.
The gateway also serves the interactive API reference at /docs and each service’s OpenAPI
document. See API & integration.
The apps
Section titled “The apps”The admin app and the worker app are clients of the same public API, through the gateway, with no private access to any service. What a person sees in them is what their permissions allow through the API.