NEXUS WMS

NEXUS is an international, multi-tenant warehouse-management system implemented as a strict-TypeScript modular monorepo. The delivered vertical slices use real PostgreSQL state, ledger-backed inventory mutations, scoped authorization, idempotent commands, audit/outbox records, a responsive enterprise desktop UI, and a scan-first PWA workspace.

The source brief was normalized into OPTIMIZED_PROMPT.md and an approved, testable contract in PRODUCT_SPEC.md. Delivery status is tracked honestly in docs/FEATURE_MATRIX.md.

What runs

• apps/web: Next.js 16 App Router/React 19 UI with desktop, mobile, light/dark, compact inventory, command palette, nine locale routes, and native Persian/Arabic RTL.
• apps/api: NestJS 11 REST API with OpenAPI, signed database-backed sessions, tenant/warehouse permission scopes, structured correlation errors, Prisma/PostgreSQL transactions, idempotency, audit, and outbox persistence.
• packages/domain: decimal-safe quantities, availability/capacity rules, FIFO/FEFO allocation explanations, scan state machine, authorization, locale and search normalization.
• packages/i18n: parity-checked message catalogs for en, fa, ar, de, fr, it, es, ru, and tr.
• Local infrastructure: PostgreSQL 18, Redis 8, and MinIO through Docker Compose.

Implemented operational flows include receipt posting, allocation, scan-confirmed picking, idempotent shipment dispatch, transfer dispatch/short receipt, blind-count adjustment, return disposition/scrap, inventory balances/ledger, global search, and lot/serial trace.

Quick start

Prerequisites: Node.js 24 LTS, pnpm 11, and Docker Desktop/Engine.

cp .env.example .env
cp .env.example apps/api/.env
pnpm install
docker compose up -d postgres redis minio
pnpm db:generate
pnpm db:migrate
pnpm db:seed
pnpm build

Run the two processes in separate terminals:

pnpm --filter @nexus/api start
pnpm --filter @nexus/web start

Open http://localhost:3000/en/login.

Demo account (development seed only):

• Organization: NEXUS
• Email: maya@nexus.local
• Password: Nexus!2026Ops

The deterministic seed is blocked when NODE_ENV=production and resets the demo tenant’s sessions, generated workflow balances, idempotency, audit, and outbox records.

Verification

pnpm typecheck
pnpm lint
pnpm test
pnpm build

With PostgreSQL, the API, and the web process running, reset the demo state and run browser/API acceptance tests:

pnpm db:seed
pnpm test:e2e

Playwright uses an installed macOS Chrome automatically, PLAYWRIGHT_CHROME_PATH when set, or its managed Chromium on other systems. The suite verifies the production login/session proxy, persisted dashboard, keyboard command palette, inventory search, Persian RTL, wrong-scan rejection, complete mobile pick, shipment replay, tenant enforcement, receipt replay, transfer custody and shortage, count adjustment, return scrap, trace, search, and OpenAPI.

Interfaces

• Web: http://localhost:3000
• API: http://localhost:4000/api/v1
• OpenAPI UI/JSON: http://localhost:4000/api/docs and /api/docs-json
• PostgreSQL: localhost:5434
• Redis: localhost:6381
• MinIO API/console: localhost:9002 and localhost:9003

Architecture and operations

• Architecture
• Database design
• Inventory model
• API design
• Security model
• Permission matrix
• Test strategy
• Design system
• Visual QA ledger

Delivery boundary

This repository is a production-oriented core and demonstration deployment, not a claim that every optional capability in the original 5,970-line enterprise catalog is release-complete. Master-data administration, imports, webhook delivery workers, object-storage attachments, full notification persistence, comments/custom fields, camera/offline synchronization, and external provider adapters remain explicitly partial or planned in the feature matrix. Manufacturing, AI forecasting, yard, RFID, and automation remain intentionally disabled until their separate release gates and external dependencies are defined.