AnsrMart Grocery Checkout

A production-grade grocery checkout system built as an npm monorepo. It implements multi-rate GST billing, a pluggable offer engine (Strategy pattern), customer accounts with session management, Redis-backed caching, S3 image storage, SMS order notifications, and a Botanical-design React storefront — all runnable locally in a single docker compose up.

• Stack
• Architecture
• Quick start
• Environment variables
• Database
• Image pipeline
• API reference
• Domain design
• Design patterns
• Tests
• Scripts
• Production deployment
• AI usage

┌──────────────────────────────────────────────────────────────────────────┐
│  Browser                                                                 │
│  React 18 + TanStack Query (60s stale, no refetch-on-focus)             │
│  └─ /api/* proxy  └─ /images/* proxy (same-origin → S3)                │
└───────────────────────────┬──────────────────────────────────────────────┘
                            │ HTTP / nginx reverse proxy
┌───────────────────────────▼──────────────────────────────────────────────┐
│  nginx                                                                   │
│  gzip · /api/ → api:3000 · /images/ → floci:4566/ansrmart-images/       │
│  /assets/ (immutable) · SPA fallback                                     │
└───────────────────────────┬──────────────────────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────────────────────┐
│  Fastify 4 API  (apps/api)                                               │
│                                                                          │
│  Plugins (in order): helmet → cors → cookie → rate-limit                │
│                                                                          │
│  Routes          Services             Repositories                       │
│  /auth      ──▶  AuthService     ──▶  PostgresUserRepository            │
│  /users     ──▶  UserService     ──▶  PostgresRefreshTokenRepository    │
│  /catalog   ──▶  (direct repo)   ──▶  CachedCatalogRepository ──▶ Redis │
│  /quote     ──▶  BillingService  ──▶  CachedOfferRepository   ──▶ Redis │
│  /checkout  ──▶  OrderService    ──▶  PostgresOrderRepository            │
│  /addresses ──▶  (direct repo)   ──▶  PostgresAddressRepository         │
│  /admin     ──▶  AdminController ──▶  (Postgres repos, direct)          │
└───────────────────────────┬──────────────────────────────────────────────┘
                            │ domain types only — no HTTP, no SQL
┌───────────────────────────▼──────────────────────────────────────────────┐
│  Domain  (packages/domain)  — zero runtime dependencies                  │
│  money.js · cart.js · offers/ · tax/engine.js · billing/computeBill.js  │
└───────────────────────────┬──────────────────────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────────────────────┐
│  PostgreSQL 16             Redis 7            S3 / Floci                  │
│  6 migrations applied      catalog:active     ansrmart-images bucket      │
│  at container start        offers:active      81 product images           │
│                            60 s TTL           nginx-proxied same-origin   │
└──────────────────────────────────────────────────────────────────────────┘

Dependency rule: the arrow points inward only — web → api → domain. The domain package imports nothing from api or web. Its package.json has zero runtime dependencies. No layer reaches "through" another.

• Docker ≥ 24 and Docker Compose v2 (docker compose version)
• Node 20+ (only needed if running outside Docker)

git clone <repo-url> ansrmart
cd ansrmart/grocery-checkout

cp .env.example .env        # defaults work for local Docker

docker compose up --build   # builds api + web, starts all 5 services

Services come up in dependency order. The API runs migrations automatically on first start.

Web   → http://localhost:8080
API   → http://localhost:3000
DB    → localhost:5433  (ansrmart / localdevpassword)
Redis → localhost:6379
Floci → http://localhost:4566  (S3, SNS, Secrets Manager)

After containers are healthy (first run only):

docker compose exec api node db/seed.js
# Seeds 81 catalog items + offers + coupons + 1 admin account

Also first run only — extracts the product image library and pushes it to the local Floci S3 bucket:

node scripts/extract-images.js          # iconic-images-and-descriptions/ → data/image/
AWS_ENDPOINT_URL=http://localhost:4566 \
  node scripts/upload-images-to-s3.js  # data/image/ → s3://ansrmart-images/images/

Images are then served via nginx at /images/{slug}.jpg (same-origin, no CORS).

npm install

# Start postgres + redis + floci via Docker, then:
npm run dev          # api on :3000 + web on :5173, concurrently

Copy .env.example to .env. All variables have sane local-dev defaults.

Frontend build-time variable (baked into the Vite bundle):

Migrations live in db/migrations/ and are applied automatically by the API container at startup (node db/migrate.js && node apps/api/src/server.js in the Dockerfile CMD). They are also safe to run manually.

The migration runner (db/migrate.js) tracks applied migrations in a schema_migrations table. Each migration is applied in a transaction; a failure rolls back and exits with code 1.

docker compose exec api node db/seed.js

Creates: 81 active catalog items across multiple categories, a set of offers (percentage, threshold, BOGO), one FIRSTBUY10 coupon, and one admin user.

81 product images live in data/image/{slug}.jpg — this is the canonical store. On a fresh environment, upload them to S3 once:

AWS_ENDPOINT_URL=http://localhost:4566 \
  node scripts/upload-images-to-s3.js   # data/image/ → s3://ansrmart-images/images/

nginx proxies /images/{slug}.jpg → S3 internally, so the browser stays same-origin and no CORS configuration is needed.

data/image/{slug}.jpg
        │
        ▼  node scripts/upload-images-to-s3.js
s3://ansrmart-images/images/{slug}.jpg
        │
        ▼  nginx /images/ proxy
http://localhost:8080/images/{slug}.jpg   (same-origin)

Adding new images: drop {slug}.jpg files into data/image/ and re-run the upload script. The slug must match the image_slug column in the catalog_items table.

In production, point the upload script at your real S3 bucket (remove AWS_ENDPOINT_URL) and set VITE_IMAGE_BASE_URL=https://cdn.yourdomain.com/images at Docker build time. No code changes required.

Every error response uses this shape:

{
  "error": {
    "code": "UNKNOWN_ITEM",
    "message": "Item abc123 not found in catalog.",
    "field": "lines[2].itemId",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

The packages/domain package is the billing core. It has zero runtime dependencies and is framework-agnostic — it can be imported by the API, a CLI tool, or a test runner without any side effects.

All monetary values are integer paise throughout. ₹1 = 100 paise.

• Float drift is structurally impossible in any calculation path.
• The single rounding boundary is money.format(paise) — called only when producing a display string, never mid-computation.
• money.mulQuantity(paise, qty) handles fractional-kg weights: scales up, does integer math, rounds half-up once.
• money.percentage(paise, bps) uses basis points (1800 bps = 18%) to stay integer throughout.

Phase A — Category & BOGO offers    (applied against pre-discount subtotals)
Phase B — Flat cart-threshold       (applied against post-Phase-A total)
Phase C — Coupons                   (applied against post-Phase-B total)

Within each phase, offers are sorted by priority asc, then id lexicographically — fully deterministic.

Exclusive offers: if two rules share exclusive: true, only the lowest priority number wins. The other moves to skippedOffers with a reason string.

Floor invariant: every discount is max(0, computed). No bill total can go negative. A clamped-to-zero discount still appears in skippedOffers.

GST is computed per item category. The total discount is distributed across lines using the largest-remainder method — integer pieces always sum exactly to taxableAmount.

Tax rates (illustrative — not authoritative tax law):

Key invariant: grandTotal === taxableAmount + totalTax — asserted in the integration test suite.

// 1. packages/domain/src/offers/BundleOffer.js
export class BundleOffer extends OfferRule {
  isEligible(ctx) {
    const ok = ctx.lines.some(l => this.params.itemIds.includes(l.item.id));
    return { eligible: ok, reason: ok ? '' : 'Bundle item not in cart' };
  }
  apply(ctx) {
    return [this._discount(this.params.amountPaise, 'cart')];
  }
}

// 2. offers/registry.js — one line:
OFFER_REGISTRY['bundle'] = BundleOffer;

// 3. INSERT an offer row with type='bundle'. Done.

packages/domain
  money.test.js          22 tests  — arithmetic, rounding, edge cases
  cart.test.js           14 tests  — resolution, merging, unknown items
  offers.test.js         28 tests  — all 4 strategies, stacking, OCP seam
  tax.test.js            10 tests  — multi-rate breakdown, largest-remainder
  computeBill.test.js    13 tests  — worked examples, invariants, 500-item linearity

apps/api
  billing.test.js        17 tests  — full HTTP round-trips with in-memory repos

Total: 104 tests

npm run verify        # lint + all tests (CI gate)
npm run test          # tests only
npm run test:domain   # domain package only
npm run test:api      # API package only

• Set DB_SSL=true — required by AWS RDS
• Create DB_SECRET_NAME in AWS Secrets Manager → { "password": "..." }
• Create JWT_SECRET_NAME in AWS Secrets Manager → { "secret": "..." }
• Remove AWS_ENDPOINT_URL from env (or leave blank) — blank = real AWS
• Set WEB_ORIGIN to your production frontend domain
• Set NOTIFICATIONS_ENABLED=true, NOTIFICATIONS_PROVIDER=sns, SNS_ORDER_TOPIC_ARN=arn:aws:sns:...
• Set VITE_IMAGE_BASE_URL=https://cdn.yourdomain.com/images at Docker build time
• Run image pipeline once against real S3: node scripts/extract-images.js && node scripts/upload-images-to-s3.js
• Run docker compose exec api node db/seed.js (first deploy only)

Everything else — migrations, API code, nginx config, Docker builds — is identical between local and production. The local Floci emulator is a 1:1 wire-compatible replacement for real AWS; switching to production is purely an environment variable change.

• Catalog cache: Redis-backed with 60s TTL; admin writes invalidate immediately. Scales horizontally without cache-stampede risk.
• Rate limiting: Uses Redis as the shared store (@fastify/rate-limit), so limits apply correctly across multiple API replicas.
• Image CDN: Set VITE_IMAGE_BASE_URL to a CloudFront distribution URL. nginx /images/ fallback is only needed locally.
• Read replicas: getPool() creates a single pool; add a read-only pool for GET routes if read throughput demands it.

See AI_USAGE.md for a full account of what was generated by AI, what was hand-authored, and what was independently verified.

The short version: the billing domain logic (packages/domain) was the most carefully supervised section — every rounding mode, stacking rule, and tax allocation was traced manually or proven via invariant tests. API scaffolding, repository adapters, and React components were AI-generated and then inspected. Architecture decisions, the domain contract (CONTRACT.md), and module boundaries were human-authored first and used as specs for code generation.