CommerceOS Complete Implementation

CommerceOS is a reusable commerce operating layer for platforms that need products, carts, checkout, orders, POS, discounts, tax, inventory, permissions, events and analytics.

This implementation is a complete runnable TypeScript starter. It uses an in-memory repository so you can run and test it immediately. For production, replace the repositories with PostgreSQL/Prisma/TypeORM adapters and connect real SecurityOS, FinanceOS, payment gateway and message broker services.

What is included

• Product and category management
• Cart lifecycle
• Checkout engine
• Order lifecycle and status transitions
• POS sale flow
• Inventory tracking and rollback on cancellation
• Discount engine
• Tax calculation per product
• Pricing engine using minor currency units
• Event bus for OS-to-OS communication
• Permission middleware using demo roles
• Analytics summary
• PostgreSQL schema example
• Tests

Money format

All money values are stored as integer minor units.

Example for INR:

• 29900 = ₹299.00
• 59800 = ₹598.00

Run locally

npm install
npm run dev

The API starts at:

http://localhost:4000

Health check:

curl http://localhost:4000/health

Demo tenant and seeded data

The server seeds demo data at startup:

tenantId: demo-tenant
products: Paneer Pizza, Cold Coffee
coupon: WELCOME10

Use these headers for most examples:

x-tenant-id: demo-tenant
x-role: admin

Demo roles:

• customer
• cashier
• manager
• admin
• owner

API examples

List products

curl "http://localhost:4000/commerceos/products?tenantId=demo-tenant"

Create a cart

curl -X POST http://localhost:4000/commerceos/carts \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: demo-tenant" \
  -H "x-role: customer" \
  -d '{"customerId":"CUS-1001"}'

Add item to cart

Replace CART_ID and PRODUCT_ID from the API response.

curl -X POST http://localhost:4000/commerceos/carts/CART_ID/items \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: demo-tenant" \
  -H "x-role: customer" \
  -d '{"productId":"PRODUCT_ID","quantity":2}'

Apply discount

curl -X POST http://localhost:4000/commerceos/carts/CART_ID/discount \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: demo-tenant" \
  -H "x-role: customer" \
  -d '{"code":"WELCOME10"}'

Checkout

curl -X POST http://localhost:4000/commerceos/checkout \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: demo-tenant" \
  -H "x-role: customer" \
  -d '{
    "cartId":"CART_ID",
    "customerId":"CUS-1001",
    "orderType":"delivery",
    "paymentMethod":"upi",
    "deliveryAddress":{"line1":"MG Road","city":"Bengaluru","pincode":"560001"}
  }'

POS sale

curl -X POST http://localhost:4000/commerceos/pos/sale \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: demo-tenant" \
  -H "x-role: cashier" \
  -d '{
    "cashierId":"EMP-001",
    "items":[{"productId":"PRODUCT_ID","quantity":1}],
    "paymentMethod":"cash"
  }'

Analytics summary

curl "http://localhost:4000/commerceos/analytics/summary?tenantId=demo-tenant" \
  -H "x-role: manager"

Recent events

curl http://localhost:4000/commerceos/events/recent \
  -H "x-role: admin"

Folder structure

src/
  api/                 Express routes, schemas, middleware
  domain/              Commerce domain types
  integrations/         Example OS-to-OS subscribers
  modules/              CommerceOS modules
    products/
    inventory/
    discounts/
    tax/
    pricing/
    carts/
    orders/
    checkout/
    pos/
    analytics/
  security/             Role/permission demo layer
  shared/               IDs, errors, store, events
  commerceos.ts         Composition root
  index.ts              API server
  seed.ts               Demo data

database/
  schema.sql            PostgreSQL schema example

tests/
  commerceos.test.ts    Core flow tests

OS events emitted

CommerceOS emits events that other OS layers can consume:

• product.created
• inventory.updated
• cart.created
• cart.item.added
• checkout.started
• order.created
• order.status.updated
• order.cancelled
• order.refunded
• payment.completed
• pos.sale.completed
• finance.invoice.requested
• analytics.revenue.update.requested
• automation.order.notification.requested

Production upgrade path

1. Replace InMemoryRepository with PostgreSQL repositories.
2. Replace demo permission middleware with SecurityOS JWT/RBAC.
3. Replace payment simulation with FinanceOS/payment gateway integration.
4. Replace in-memory EventBus with Kafka, RabbitMQ, NATS, Redis Streams or another broker.
5. Add idempotency keys for checkout and POS.
6. Add audit logs through SecurityOS.
7. Add observability, rate limits and background workers.

Planning Alignment

• Official package: @appneurox/commerceos
• Manifest: manifest.json
• Domain API namespace: /v1/commerce
• Modes: standalone and PlatformOS integrated
• Related systems: FinanceOS, ClientOS

See docs/planning.md for the planning contract applied from APPNEURAL Plannings/OSs.