Find products, SKUs, barcodes, orders, suppliers, customers, warehouses, batches and serial numbers
The design document behind this inventory system: the engine, data model, API, access control, events and deployment, with live tests you can run against a fresh copy of the sample data.
A multi-warehouse inventory system built movement-first: stock changes only by appending immutable ledger rows, in the same transaction as the balance they change. This document covers the whole design, from the engine to deployment, and marks what runs in this demo and what is designed for production.
The engine, access rules, approvals, outbox and signed webhooks on this page run in your browser on a seeded database; blocks tagged Runs in this demo are working code you can exercise in the other pages. The Rust and Axum backend, PostgreSQL, Redis, RabbitMQ and Docker setup are tagged Designed: a plan, not a running service.
The demo implements the domain the production backend would own, so the backend can be ported from it rather than invented beside it.
Runs in this demo
Working code over a seeded database, in your browser
makeTx): operations run on a copy-on-write view of the database; any error discards it, and a success commits in one assignment.authorize), warehouse scope for warehouse managers, separation of duties and approval chains configured as data.orgId, reads go through a tenant-scoped repository, and another tenant's id answers NOT_FOUND.Designed for production
Specified on this page; not deployed
/api/v1, documented with OpenAPI through utoipa.SELECT … FOR UPDATE on balance rows.Six months of history (April to September 2026) replayed through the same operations the pages call, for two fictional companies: Northwind Supply Co. and Globex Retail.
Stock movements
3,271
Immutable ledger rows
Stock positions
292
Product × warehouse balances, 20,017 units on hand
Batches
277
5 with stock expiring within 30 days
Serial numbers
1,048
617 in stock, the rest sold or written off
Documents
1,006
324 purchasing, 555 sales, 127 stock
Outbox events
99
68 signed webhook deliveries
Counted live for Northwind Supply Co. through the same repository every page reads from; the numbers move as you use the demo.
A React single-page app in front of one stateless Rust API. PostgreSQL holds the truth, Redis holds what can be thrown away, RabbitMQ carries everything that can happen after the response.
The request path runs top to bottom: browser, Nginx, the API. Everything slow or unreliable (email, webhooks, reports, connector sync) leaves the request through the outbox and runs in workers.
Each module owns its tables. Purchasing never inserts a movement; it calls the inventory service, which is the only code that changes stock.
In the demo the modules are TypeScript files in src/data/inventory; the store's api object stands in for the HTTP layer, one method per endpoint. Porting means moving each operation behind a handler, not rewriting its rules.
The layout from spec §50, annotated with what lives where.
Backend (Rust)
Frontend (React + Vite)
The engine is the source of truth, and the only code that changes stock. Every change is an immutable movement written in the same transaction as the balance it moves; balances are a fast cache of the ledger that can be rebuilt from it at any time.
Spec §9 asks for BEGIN, update the balance, create the movement, create the audit event, COMMIT, and ROLLBACK on any failure. Here is that path step by step, as the demo runs it and as PostgreSQL will.
BEGIN
makeTx(db, ctx) opens a copy-on-write view; tables are copied on first write.BEGIN, then SET LOCAL app.org_id so row-level security applies.Authorize
authorize(ctx, perm), then the tenant and warehouse checks on every row loaded.Validate
validator on the DTO first, business rules in the service.Lock balances
SELECT … FOR UPDATE on each balance row, in product and warehouse order to avoid deadlocks.Post movements
post() writes one immutable row per bucket with before and after, and bumps the balance version.INSERT into inventory_movements, UPDATE inventory_balances; CHECK constraints reject negatives.Audit and outbox
tx.audit() and tx.emit(); dispatch(tx) writes the outbox and routes events.INSERT into audit_logs and outbox_events in the same transaction.COMMIT
COMMIT. The outbox relay publishes to RabbitMQ afterwards.Any error, at any step: ROLLBACK
Operations throw a RuleError (VALIDATION, CONFLICT, FORBIDDEN, NOT_FOUND or INSUFFICIENT_STOCK). The working copy is dropped, so a five-line transfer that fails on line five leaves no trace of lines one to four. The live test “Issuing more than is available” proves it.
In the API the same codes become 422, 409, 403, 404 and 409 responses in the error envelope.
1// src/stores/inventory-store.ts — the whole commit path in this demo2export function transact<T>(fn: (tx: Tx) => T): T {3 const s = useInvStore.getState()4 const ctx = buildAccess(s.db, s.userId, s.orgId) // user + org + role + permissions5 const tx = makeTx(s.db, ctx) // BEGIN (copy-on-write)6 const result = fn(tx) // authorize, validate, post, audit, emit7 dispatch(tx) // outbox → notifications, webhooks8 useInvStore.setState({ db: tx.db }) // COMMIT9 return result // a throw above = ROLLBACK10}Each product in each warehouse has one balance with four stored buckets. Available is derived.
On hand
20,017
Physically in the warehouse and sellable or promised. Includes reserved units; excludes damaged and in transit.
Reserved
102
Promised to confirmed sales orders. Still on the shelf, so on hand doesn't change when stock is reserved.
Available
19,915
What can still be promised: on hand minus reserved. Derived, never stored.
Damaged
12
Set aside and not sellable, until it's returned to the supplier or written off.
In transit
176
Dispatched from another warehouse and not received yet. Counts at the destination only on receipt.
Units across the 292 stock positions you can see, summed from the balances the engine maintains.
The fourteen movement types from spec §9. A posting writes one row per bucket it changes, grouped, with the quantity before and after, the unit cost, the batch or serials, the document and the user.
Checked before every commit; breaking one throws and the transaction is discarded. The live tests re-check all of them on a fresh copy of the data.
On hand, reserved, damaged and in transit never go below zero.
post() before commit; CHECK constraints in PostgreSQL.
Reserved never exceeds on hand.
post(); CHECK (reserved <= on_hand).
Movements are append-only. A mistake is corrected by a new movement, never by editing one.
No operation edits a movement; a trigger rejects UPDATE and DELETE in PostgreSQL.
Each movement continues the last one for its balance and bucket: before equals the previous after.
post() writes before and after; checkInvariants walks the chain.
Balances equal a replay of the ledger.
checkInvariants; a nightly reconciliation job in production.
Reserved stock equals active reservations; batch and serial records agree with the balances.
The engine updates them in the same posting; checkInvariants verifies.
Every movement names its document, user and time, and quantities are whole units.
Required fields on Movement; NOT NULL columns and integer types.
Batch-tracked stock is picked by the organization's issuing strategy: FEFO takes the earliest expiry first, FIFO the earliest received. Expired and quarantined batches are never reserved; serialized stock is picked by serial number.
Hand sanitizer 500 ml at Bhiwandi DC, in the order the engine would pick them (earliest expiry first):
The strategy is a setting, not code: pickOrder(batches, strategy) sorts the candidates and allocate() walks them until the quantity is covered, or throws INSUFFICIENT_STOCK naming how much is free. Reservations remember their allocations, so shipping takes exactly the batches that were promised.
Spec §44: FIFO, weighted average and standard cost, in a service of their own rather than in controllers. Today's values for the stock you can see:
FIFO
₹2,12,06,573
20,017 units on hand
Replays on-hand movements into cost layers; outbound units consume the oldest layers first. Value is what's left in the layers.
Weighted average
Used for reports₹2,12,31,953
20,017 units on hand
Each receipt re-averages: (on hand × average + received × unit cost) ÷ (on hand + received). Kept on the balance row.
Standard cost
₹2,18,24,954
20,017 units on hand
On hand × the product's standard cost. Purchase price variance is reported separately.
Computed now by repo.valuation() over the same ledger. The service reads movements and balances and never writes, so switching the method in Settings changes reports, not history. Differences between the three are real: FIFO values stock at the latest receipts, the average smooths them, standard cost ignores them.
Spec §61: every inventory change has a traceable history from the document that caused it to the balance it changed. Tinted steps post movements.
Purchase to stock
Nothing changes stock until goods are received and accepted.
Purchase order
Draft, approval chain by amount, then ordered. No stock change.
Goods receipt
Accepted and rejected quantities; batch, serial and expiry checked. Partial receipts allowed.
Inventory movement
One row per accepted line at the net unit price.
PURCHASE_RECEIPT
Inventory balance
On hand up, weighted average cost recalculated, batch or serials created.
Sale to shipment
Creating or confirming an order never reduces physical stock.
Sales order
Confirmed after a credit check and, above a threshold, approval.
Reservation
Available down, reserved up; FEFO picks the batches.
STOCK_RESERVATION
Shipment
Pack, then ship; the reservation is consumed and an invoice raised.
Inventory movement
Release and sale posted as one group.
STOCK_RELEASE + SALE
Inventory balance
On hand down by the shipped quantity; reserved back where it was.
Warehouse transfer
Destination stock is added only when goods are received.
Warehouse transfer
Source, destination and lines; approval above 20 units.
Transfer out
Source on hand down; batches and serials leave with the goods.
TRANSFER_OUT
In transit
Shown at the destination, not sellable, not in on hand.
Transfer receipt
Line by line; partial receipts allowed.
Transfer in
In transit down, destination on hand up.
TRANSFER_IN
A normalized PostgreSQL schema with UUID keys, foreign keys and constraints that make corrupt stock unrepresentable, designed for 100,000+ products and 10 million+ movements (spec §53).
Grouped by module. pk, fk and uq mark primary, foreign and unique keys; null marks an optional column. Constraints are listed under each table.
The heart of the system. Movements are the append-only truth; balances are the per-product, per-warehouse cache updated in the same transaction.
One row per product and warehouse, locked FOR UPDATE when posting.
One immutable row per bucket change, with before and after.
Stock promised to a sales order line, with its batch or serial picks.
Lots with expiry, per product and warehouse.
One row per serialized unit, from receipt to sale and warranty.
gen_random_uuid(). Join tables use a composite key instead.
NOT NULL on every tenant table, child rows included, and the first column of every index.
Defaults to now().
Set by a trigger on update.
Null for rows written by workers.
Last editor.
Soft delete, only on tables marked soft delete.
54 tables in 8 groups. Money is numeric, quantities are integers in the product's base unit, timestamps are timestamptz.
Spec §34's list, each mapped to the index that serves it and the query it exists for.
organization_id on every tenant row, enforced twice: in the repositories, and by row-level security as the backstop.
In the demo every row carries orgId. Reads go through createRepo(db, ctx), which filters by the signed-in organization, and writes load rows through ownRow(), which answers NOT_FOUND for another tenant's id, exactly as for a missing one. Switch to the Globex admin in the account menu to see a different company in the same database.
In PostgreSQL the API sets app.org_id for each transaction from the verified token, and a policy on every tenant table compares it with the row. A repository that forgets its where organization_id = $1 returns nothing instead of another company's stock. Composite foreign keys stop a line pointing at another tenant's order.
Platform staff (super admin) use a separate role that sets the organization they are supporting; every such session is audited.
1-- The same policy on every tenant table (generated by a migration helper).2alter table inventory_movements force row level security;34create policy tenant_isolation on inventory_movements5 using (organization_id = current_setting('app.org_id', true)::uuid)6 with check (organization_id = current_setting('app.org_id', true)::uuid);78-- The API connects as inventory_app (no BYPASSRLS) and scopes each transaction9-- with the organization from the verified token, never from the request body.10begin;11select set_config('app.org_id', $1, true); -- true = local to this transaction12-- … every query in the request …13commit;1415-- Composite keys stop a child row pointing at another tenant's parent.16alter table purchase_order_items17 add foreign key (organization_id, purchase_order_id)18 references purchase_orders (organization_id, id);Offsets get slower with every page and skip rows when new movements arrive. Keyset pagination asks for rows after the last one seen, so page 5,000 costs the same as page 1.
1-- GET /api/v1/inventory/movements?product_id=…&limit=50&cursor=eyJzZXEiOjQ4MjF92select id, seq, movement_type, bucket, warehouse_id, qty, qty_before, qty_after, created_at3from inventory_movements4where organization_id = $15 and product_id = $26 and seq < $3 -- the cursor: the last seq on the previous page7order by seq desc8limit 51; -- one extra row says whether another page exists9-- Served by movements_product_history, whatever page you are on.The cursor is opaque to clients (base64 of the last sort key); responses carry meta.next_cursor and meta.has_more. Lists that sort by a timestamp page on (created_at, id) so ties are stable.
Live: the Movements page calls repo.queryMovements(filter, { limit, cursor }), the same keyset shape. Its first page here returns 50 of 3,271 rows with next cursor seq 3222.
Balances and movements with the constraints that keep stock honest, the indexes the reads need, and a trigger that makes the ledger append-only.
1-- migrations/20260401090000_inventory_ledger.sql2-- Assumes products and warehouses carry unique (organization_id, id) for composite keys.3create type movement_type as enum (4 'PURCHASE_RECEIPT', 'SALE', 'SALES_RETURN', 'PURCHASE_RETURN', 'TRANSFER_OUT', 'TRANSFER_IN',5 'ADJUSTMENT_IN', 'ADJUSTMENT_OUT', 'DAMAGE', 'LOSS', 'FOUND', 'OPENING_BALANCE',6 'STOCK_RESERVATION', 'STOCK_RELEASE'7);8create type stock_bucket as enum ('on_hand', 'reserved', 'damaged', 'in_transit');910create table inventory_balances (11 id uuid primary key default gen_random_uuid(),12 organization_id uuid not null references organizations (id),13 product_id uuid not null,14 warehouse_id uuid not null,15 on_hand integer not null default 0,16 reserved integer not null default 0,17 damaged integer not null default 0,18 in_transit integer not null default 0,19 avg_cost numeric(14, 4) not null default 0,20 version bigint not null default 0,21 updated_at timestamptz not null default now(),22 constraint balances_on_hand_not_negative check (on_hand >= 0),23 constraint balances_reserved_within_on_hand check (reserved >= 0 and reserved <= on_hand),24 constraint balances_other_buckets_not_negative check (damaged >= 0 and in_transit >= 0),25 constraint balances_one_per_product_warehouse unique (organization_id, product_id, warehouse_id),26 foreign key (organization_id, product_id) references products (organization_id, id),27 foreign key (organization_id, warehouse_id) references warehouses (organization_id, id)28);2930create table inventory_movements (31 id uuid primary key default gen_random_uuid(),32 organization_id uuid not null references organizations (id),33 seq bigint not null,34 group_id uuid not null,35 movement_type movement_type not null,36 bucket stock_bucket not null,37 product_id uuid not null,38 warehouse_id uuid not null,39 batch_id uuid references batches (id),40 qty integer not null,41 qty_before integer not null,42 qty_after integer not null,43 unit_cost numeric(14, 4) not null,44 ref_type text not null,45 ref_id uuid not null,46 user_id uuid not null references users (id),47 request_id text not null,48 created_at timestamptz not null default now(),49 constraint movements_qty_not_zero check (qty <> 0),50 constraint movements_after_follows_before check (qty_after = qty_before + qty),51 constraint movements_seq_per_org unique (organization_id, seq),52 foreign key (organization_id, product_id) references products (organization_id, id),53 foreign key (organization_id, warehouse_id) references warehouses (organization_id, id)54);5556create index movements_product_history on inventory_movements (organization_id, product_id, warehouse_id, seq desc);57create index movements_by_type on inventory_movements (organization_id, movement_type, created_at desc);58create index movements_by_document on inventory_movements (organization_id, ref_type, ref_id);59create index balances_by_warehouse on inventory_balances (organization_id, warehouse_id);6061-- The ledger is append-only: a correction is a new movement, never an edit.62create function forbid_movement_changes() returns trigger language plpgsql as $$63begin64 raise exception 'inventory_movements is append-only (% is not allowed)', tg_op65 using errcode = 'restrict_violation';66end;67$$;6869create trigger inventory_movements_append_only70 before update or delete on inventory_movements71 for each row execute function forbid_movement_changes();7273revoke update, delete, truncate on inventory_movements from inventory_app;7475alter table inventory_balances enable row level security;76alter table inventory_movements enable row level security;Sketches of the Rust code that matters most: how a request is authorized and scoped, how stock is posted under a row lock, how errors reach the client without leaking internals, and how credentials are handled. Written for this design, not extracted from a running service.
Axum 0.8, SQLx 0.8 with compile-time checked queries, thiserror, utoipa, argon2 and jsonwebtoken. No unwrap() in request paths.
1// src/purchasing/handlers.rs2use axum::{extract::State, Json};3use validator::Validate;45use crate::auth::{AuthUser, Permission};6use crate::errors::{ApiResult, AppError};7use crate::http::Created;8use crate::purchasing::{repo, schemas::{GoodsReceiptDto, PostGoodsReceipt}, service};9use crate::AppState;1011/// POST /api/v1/goods-receipts12#[utoipa::path(13 post,14 path = "/api/v1/goods-receipts",15 tag = "purchasing",16 request_body = PostGoodsReceipt,17 responses(18 (status = 201, description = "Receipt posted", body = GoodsReceiptEnvelope),19 (status = 403, description = "Missing purchase.receive"),20 (status = 404, description = "Order not found in your organization or warehouses"),21 (status = 409, description = "Order is not open for receiving"),22 (status = 422, description = "Validation failed"),23 ),24 security(("bearer" = []))25)]26pub async fn post_goods_receipt(27 State(state): State<AppState>,28 user: AuthUser, // extractor: verified JWT -> user, organization, roles, warehouse scope (401 if absent)29 Json(body): Json<PostGoodsReceipt>,30) -> ApiResult<Created<GoodsReceiptDto>> {31 user.require(Permission::PurchaseReceive)?; // 403 when the role lacks purchase.receive32 body.validate()?; // 422 with one entry per invalid field3334 // BEGIN, then set_config(app.org_id) so row-level security applies to every query below.35 let mut tx = state.db.begin_for(&user).await?;3637 // Tenant check: the repository filters by organization, and RLS would too.38 let po = repo::find_order_for_update(&mut tx, user.org_id, body.purchase_order_id)39 .await?40 .ok_or(AppError::NotFound("purchase order"))?;4142 // Resource ownership: an order for a warehouse outside the caller's scope43 // answers exactly like a missing one, so its existence is not revealed.44 if !user.can_reach(po.warehouse_id) {45 return Err(AppError::NotFound("purchase order"));46 }4748 let receipt = service::receive_goods(&mut tx, &user, &po, body).await?; // posts PURCHASE_RECEIPT movements49 tx.commit().await?; // an early return above drops tx, which rolls back50 Ok(Created(receipt.into()))51}What to notice
AuthUser extractor rejects the request with 401 before the handler runs; the handler never parses a token.authorizeWarehouse.A REST API under /api/v1 with one consistent envelope. In the demo each endpoint is a method on the store's api object that runs the same operation in a local transaction, so the table below is also a map of the code.
Mirrors src/stores/inventory/api.ts, one row per method, plus the main reads. Authentication endpoints are in section 7.
94 endpoints. Every one declares its permission (spec §52, rule 15); none relies on the client hiding a button.
Exactly as spec §32. Lists put pagination in meta; errors put one entry per problem in errors.
1{2 "success": true,3 "data": {},4 "message": null,5 "errors": null,6 "meta": {}7}1{2 "success": false,3 "data": null,4 "message": "Validation failed",5 "errors": []6}Operations in the demo throw a RuleError with one of five codes; httpStatus in rules.ts already maps each to the status the API returns. Messages say what to do next.
/api/v1. Additive changes stay in v1; a breaking change ships as v2 beside it.?limit= (1–100, default 50) and an opaque ?cursor=. Responses carry meta.next_cursor and meta.has_more.?status=ORDERED&from=2026-09-01; unknown parameters are a 422, not ignored.?sort=-created_at,number: a minus for descending; only indexed fields are sortable.Idempotency-Key header; the first response is stored for 24 hours and replayed for retries.If-Match and gets 409 if someone else saved first.X-Request-Id, also written to logs and audit rows, so a support ticket leads straight to the trace.Spec §54: the document is generated from the handlers with utoipa, so it can't drift from the code, and served with Swagger UI in development.
1// src/openapi.rs2use utoipa::OpenApi;3use utoipa_swagger_ui::SwaggerUi;45#[derive(OpenApi)]6#[openapi(7 info(title = "Inventory API", version = "1.0.0"),8 paths(purchasing::handlers::post_goods_receipt /* , every other handler */),9 components(schemas(PostGoodsReceipt, GoodsReceiptDto, ErrorEnvelope, PageMeta)),10 modifiers(&BearerAuth),11 tags((name = "inventory"), (name = "purchasing"), (name = "sales"), (name = "admin"))12)]13pub struct ApiDoc;1415pub fn router(state: AppState, config: &Config) -> Router {16 let api = Router::new().nest("/api/v1", routes::v1()).with_state(state);17 if config.swagger_ui {18 // Development and staging only; production serves no docs UI.19 return api.merge(SwaggerUi::new("/docs").url("/api-docs/openapi.json", ApiDoc::openapi()));20 }21 api22}Every handler carries a #[utoipa::path] with its request body, responses and security, as in the goods-receipt handler in section 5. DTOs derive ToSchema.
CI generates openapi.json and the SPA's TypeScript types from it (openapi-typescript), so a changed field breaks the frontend build rather than a customer's screen. A contract test fails if the checked-in document and the generated one differ.
Authentication proves who is calling; authorization decides, on the server and for every request, what they may do in which organization and warehouse. Hiding a button in the SPA is a courtesy, never the check.
Spec §28: authenticated user, organization, role, permission, resource ownership. In this order, before any row is written.
JWT signature, expiry and a live session
Persona switcher in place of sign-in; buildAccess(db, userId)
The token's organization; rows filtered by it, RLS as backstop
createRepo filters by orgId; ownRow answers NOT_FOUND
The user's roles in that organization
roleById[user.roleId], with the org's RolePermission row
The role grants the module.action the endpoint declares
authorize(ctx, perm) throws FORBIDDEN
Warehouse scope, and separation of duties on approvals
authorizeWarehouse, canDecide
Tenant and scope failures answer 404, not 403: telling a Globex user that a Northwind order exists is itself a leak. The live tests in section 11 run each link of this chain against real operations.
What each built-in role can do, module by module.
Built live from roles in src/data/inventory/rbac.ts: 9 roles over 26 permissions in 11 modules. Admins can tune the non-admin roles for their organization in Settings, Roles.
Spec §27's six entities. In the demo, users carry a role and warehouse list, and RolePermission rows let each organization tune non-admin roles.
Organization
The tenant
User
Belongs to one organization (platform staff to none)
UserRole
User × role, with warehouse scope
Role
Nine built in; organizations can add their own
RolePermission
What a role may do in one organization
Permission
A module.action key
Permissions are module.action keys: the spec's list plus inventory.approve, purchase.receive, sales.fulfil, audit.read and integrations.manage, which the workflows need to separate duties (the buyer who raises an order isn't the one who receives it).
Spec §26. The demo switches between personas from the account menu instead of signing in.
Spec §39.
Anything that can happen after the response does: notifications, email, webhooks, reports and connector sync. Operations only emit events; a transactional outbox makes the event exist if and only if the change does.
The demo runs the same routing in-process (dispatch.ts is the stand-in for the RabbitMQ consumers); production puts a broker between them.
One transaction
Outbox relay
inventory.events
notifications32 eventsstock.*, approval.*, transfer.received, expiry.warning. Writes in-app notifications for the users each event concerns, per channel settings. 3 attempts, then notifications.dead.
email32 eventssame keys, when the kind's channels include email. Renders and sends through the email provider. 5 attempts with backoff, then email.dead.
webhooks68 eventsthe eleven webhook event types. One signed POST per subscribed endpoint. TTL retry queues at 1, 2, 4, 8, 16 minutes; failed after 6 attempts.
reports15 eventsinventory.adjusted, purchase.received, sales.completed. Refreshes rollups and builds export files. 3 attempts, then reports.dead.
syncDesignedinventory.updated, product.*. Pushes stock and catalog to connected ERPs and storefronts. Backoff per connector; a sync job records each run.
dispatch() with the same rules. Retry policies other than webhooks are designed.Outbox events
99
17 approval.requested, 17 inventory.updated
Webhook deliveries
68
191 attempts in total
Idempotency keys
68 of 68
Deliveries keyed by their event id
Retry schedule
6 attempts
Waits of 1, 2, 4, 8, 16 min
One endpoint in the sample data points at a broken staging URL on purpose, so retries and the failure alert are visible in Integrations.
1// src/outbox/relay.rs (designed): publish committed events, at least once.2loop {3 let mut tx = db.begin().await?;4 let batch = sqlx::query_as!(OutboxRow,5 "select * from outbox_events where published_at is null6 order by created_at limit 100 for update skip locked")7 .fetch_all(&mut *tx).await?;8 for ev in &batch {9 channel.basic_publish("inventory.events", &ev.event_type, ev.payload_bytes(), props(ev)).await?10 .await?; // wait for the broker's publisher confirm11 }12 mark_published(&mut tx, &batch).await?;13 tx.commit().await?;14 if batch.is_empty() { tokio::time::sleep(POLL_INTERVAL).await; }15}Each delivery is signed with the endpoint's secret: t=<unix seconds>,v1=<hex HMAC-SHA256 of “t.body”>. The timestamp is inside the signature, so a captured request can't be replayed later.
1// A receiver in Node: verify before trusting the body.2import { createHmac, timingSafeEqual } from "node:crypto"34export function verifyInventoryWebhook(rawBody: string, header: string, secret: string, nowSecs = Date.now() / 1000) {5 const parts = Object.fromEntries(header.split(",").map((kv) => kv.trim().split("=") as [string, string]))6 const t = Number(parts.t)7 if (!parts.v1 || !Number.isFinite(t)) return false8 if (Math.abs(nowSecs - t) > 300) return false // too old: replayed, or clocks disagree910 const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest()11 const given = Buffer.from(parts.v1, "hex")12 return given.length === expected.length && timingSafeEqual(given, expected)13}1415// Then deduplicate: the payload id (also the Idempotency-Key header) is the event id.16// Store it with a unique constraint and return 200 for a duplicate without acting twice.Newest delivery: sales.completed to Analytics pipeline (staging)
X-Inventory-Signature
t=1790661314,v1=1beddb09b8b342b816e45be87f661e5e673446d54d83be8eed43dea17f2372eb
Body: 204 bytes, idempotency key evt-c08
Recomputed just now in your browser with verifySignature(): HMAC-SHA256 over `${t}.${body}`, the scheme any receiver can check with a standard library.
Redis holds only what can be rebuilt from PostgreSQL, with a TTL that bounds how stale it can get. Every request is traceable end to end by one id, and the service says plainly whether it can take traffic.
Keys are namespaced by purpose and organization. Invalidation is event-driven through the outbox; the TTL is the safety net if an event is missed.
JSON lines through tracing, one per request plus one per error, with the request id Nginx assigns (X-Request-Id) propagated to logs, spans, audit rows and outbox events.
1{2 "ts": "2026-09-29T11:40:02.118+05:30",3 "level": "INFO",4 "msg": "request completed",5 "request_id": "req_7f3a9c",6 "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",7 "org_id": "0c8e…",8 "user_id": "4b2e…",9 "method": "POST",10 "route": "/api/v1/goods-receipts",11 "status": 201,12 "latency_ms": 38,13 "db_ms": 21,14 "movements_posted": 215}Personal data stays out of logs: ids, not names or emails. Traces go to an OpenTelemetry collector; a log line, its trace and the audit rows it wrote share the request id.
Live: the demo's audit log already carries it. The newest entry, “SO-2026-00183” (sales_order.completed) by Imran Sheikh at 29 Sep 2026, 11:25, has request id req_…. The six months of sample history were replayed as one long transaction, so those rows share it; approve or receive something elsewhere in the demo and the newest entry here will carry that request's own id. Every entry also records the IP address and user agent.
Spec §38: /health for liveness and /ready for readiness, checking PostgreSQL, Redis and RabbitMQ in parallel with short timeouts.
1// src/routes/health.rs2/// Liveness: the process is up. No dependencies, so a database outage never restarts pods.3pub async fn health() -> Json<Value> {4 Json(json!({ "status": "ok" }))5}67/// Readiness: can this instance serve traffic? Load balancers stop routing on 503.8pub async fn ready(State(s): State<AppState>) -> (StatusCode, Json<Value>) {9 let (pg, redis, mq) = tokio::join!(10 timed(sqlx::query("select 1").execute(&s.db)),11 timed(s.redis.ping()),12 timed(async { s.amqp.status().connected().then_some(()).ok_or("disconnected") }),13 );14 let ok = pg.ok && redis.ok && mq.ok;15 let body = json!({ "status": if ok { "ready" } else { "degraded" },16 "checks": { "postgres": pg, "redis": redis, "rabbitmq": mq } });17 (if ok { StatusCode::OK } else { StatusCode::SERVICE_UNAVAILABLE }, Json(body))18}1{2 "status": "ready",3 "checks": {4 "postgres": { "ok": true, "latency_ms": 3 },5 "redis": { "ok": true, "latency_ms": 1 },6 "rabbitmq": { "ok": true, "latency_ms": 4 },7 "migrations": { "ok": true, "version": 20260401090000 }8 }9}Prometheus metrics from the API and workers, RabbitMQ and PostgreSQL exporters, dashboards in Grafana.
One backend image serves both the API and the workers; Nginx fronts the static SPA and the API. The pipeline won't ship anything that didn't pass every check.
Spec §57, in GitHub Actions.
Deploy runs only when every earlier job passed (the image job needs both test jobs, deploy needs the image job), only from main, and only after an approval on the production environment. A failed scan stops the release like a failed test.
Spec §55–57. Samples, not a running setup: this demo runs in the browser and has no backend of its own.
1# docker-compose.yml: local development and single-host staging2name: inventory34services:5 nginx:6 image: nginx:1.27-alpine7 ports: ["80:80", "443:443"]8 volumes:9 - ./deploy/nginx.conf:/etc/nginx/nginx.conf:ro10 - ./deploy/certs:/etc/nginx/certs:ro11 depends_on:12 frontend: { condition: service_started }13 backend: { condition: service_healthy }1415 frontend:16 build: { context: ./frontend, dockerfile: ../Dockerfile.frontend }17 expose: ["8080"] # static build served by an unprivileged nginx1819 backend:20 build: { context: ./backend, dockerfile: ../Dockerfile.backend }21 env_file: .env22 expose: ["8000"]23 depends_on:24 postgres: { condition: service_healthy }25 redis: { condition: service_healthy }26 rabbitmq: { condition: service_healthy }27 healthcheck:28 test: ["CMD", "/app/inventory-api", "healthcheck"] # distroless has no curl29 interval: 10s30 timeout: 3s31 retries: 53233 worker:34 build: { context: ./backend, dockerfile: ../Dockerfile.backend }35 command: ["worker"] # same image: outbox relay and queue consumers36 env_file: .env37 depends_on:38 backend: { condition: service_healthy }3940 postgres:41 image: postgres:17-alpine42 environment:43 POSTGRES_DB: inventory44 POSTGRES_USER: inventory45 POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set it in .env}46 volumes: [pgdata:/var/lib/postgresql/data]47 healthcheck:48 test: ["CMD-SHELL", "pg_isready -U inventory -d inventory"]49 interval: 5s50 retries: 105152 redis:53 image: redis:7.4-alpine54 command: ["redis-server", "--maxmemory", "256mb", "--maxmemory-policy", "volatile-lru"]55 healthcheck:56 test: ["CMD", "redis-cli", "ping"]57 interval: 5s5859 rabbitmq:60 image: rabbitmq:4.0-management-alpine61 environment:62 RABBITMQ_DEFAULT_USER: inventory63 RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD:?set it in .env}64 volumes:65 - rabbitdata:/var/lib/rabbitmq66 - ./deploy/rabbitmq-definitions.json:/etc/rabbitmq/definitions.json:ro # exchanges, queues, DLX policies67 healthcheck:68 test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]69 interval: 10s7071volumes:72 pgdata:73 rabbitdata:Spec §48's pyramid for the production system, and a set of live tests you can run right here against a fresh copy of the sample data.
Playwright, one spec per journey, each starting from a clean seeded database.
Real checks on a fresh buildSeed() copy: the ledger invariants, authorization (permission, warehouse scope, separation of duties, tenant isolation) and the engine's behaviour, each through the operations the pages call.
19 tests ready
Runs in your browser against a fresh buildSeed() copy, never the data you're editing.
checkInvariants() on the fresh seed: the ledger replays into the balances, batches and serials exactly.
Balances equal a replay of the movement ledger
—Every movement continues the previous one (before = last after)
—No negative stock; reserved never exceeds on hand
—Reserved stock equals active reservations
—Batch quantities add up to on-hand stock
—Serial numbers match serialized stock
—Real access contexts calling real operations: permission, warehouse scope, separation of duties and tenant isolation.
A viewer can't create a purchase order
—A warehouse manager can't receive into a warehouse they don't run
—A buyer can't approve their own purchase order
—Globex can't read Northwind's products
—Globex can't change a Northwind record through the API
—A purchase manager can't post a stock adjustment
—Workflows posted through the engine, with balances compared before and after each committed transaction.
Reserving reduces available, not on hand
—Shipping takes the goods out of on hand
—A transfer adds destination stock only on receipt
—Partial receipts: 60 then 40 of 100 ordered
—FEFO reserves the batch that expires first
—Issuing more than is available rolls the whole transaction back
—The ledger still reconciles after these transactions
—Source: live-tests.ts and live-tests-engine.ts in src/components/inventory/architecture. Each write runs a real operation inside makeTx and dispatch, exactly like the store's transact; the same functions run in Node.
Spec §51 asks for twelve phases, each verified before the next. 8 of them are built in this demo; the rest are designed on this page and are the path from demo to production.
Status reflects this demo, not a deployed product.
Phase 1: Architecture
Runs in this demoArchitecture document, database ERD, API specification, folder structure, auth and inventory architecture
This page.
Phase 2: Infrastructure
DesignedDocker, PostgreSQL, Redis, RabbitMQ, backend, frontend, environment configuration
Compose, Dockerfile and .env.example in section 10.
Phase 3: Authentication
DesignedRegister, login, logout, refresh token, forgot and reset password, roles, permissions
Roles and permissions are built and checked in every operation; sign-in flows are designed.
Phase 4: Product and warehouse
Runs in this demoProducts, categories, brands, units, warehouses, locations
Catalog, import and export, barcodes, bins.
Phase 5: Inventory engine
Runs in this demoBalances, movements, reservations, adjustments, transfers, batch, serial, expiry
The ledger, allocation, valuation and invariant checks.
Phase 6: Purchasing
Runs in this demoSuppliers, purchase orders, approvals, goods receipts, purchase returns
Including partial receipts and QC rejections.
Phase 7: Sales
Runs in this demoCustomers, sales orders, reservations, shipments, sales returns
Plus invoices, payments and credit limits.
Phase 8: Reports
Runs in this demoInventory, purchase, sales, warehouse and financial reports
With CSV, Excel and PDF export.
Phase 9: Notifications and audit
Runs in this demoNotifications, email, RabbitMQ jobs, audit logs
In-app notifications, channel settings and the audit log are built; email delivery and RabbitMQ are designed.
Phase 10: Integrations
Runs in this demoWebhooks, integration framework, external API framework, sync jobs
Signed webhooks with retries and a delivery log are built; connectors are simulated, with no external calls.
Phase 11: Testing
DesignedUnit, integration, E2E, security and performance tests
The live tests in section 11 run in the browser; the suites are designed.
Phase 12: Production
DesignedProduction images, CI/CD, migration and backup strategy, monitoring, logging, deployment docs
Sections 9 and 10.
Stock contention on hot SKUs
Every reservation of a best-seller locks the same balance row; a flash sale queues requests behind it.
Short transactions with no network calls inside, lock ordering, lock_timeout with one retry, and a lock-wait metric with an alert. If one SKU still dominates, split its balance by bin.
Negative stock
A race or a bug could oversell or ship stock that isn't there.
Checked three times: in the engine before writing, by CHECK constraints, and nightly by replaying the ledger. allow_negative_stock is fixed to false.
Leaks between tenants
One missing where clause exposes another company's stock and prices.
Repository filters, row-level security forced on every tenant table, composite foreign keys, 404 for foreign ids, and cross-tenant tests in CI like the live ones here.
Webhook storms
A bulk import or count approval emits thousands of events; a slow receiver backs up the queue.
One inventory.updated per transaction listing the balances it changed (as the demo does), per-endpoint concurrency limits, a circuit breaker, TTL retry queues and a dead-letter queue.
FIFO valuation cost at scale
Replaying millions of movements for every valuation report grows with history.
Persist cost layers as receipts post and consumption as issues post, snapshot valuation at month end, and report from the snapshot plus the month's movements. Weighted average stays O(1).
Offline scanning
Warehouse Wi-Fi drops; scanners must keep working and must not double-post when they reconnect.
A PWA that queues scans in IndexedDB, each with an idempotency key; the server replays them in order and returns conflicts (stock already moved) for a person to resolve. Offline screens never promise stock.