Bakestack Backend

Bakestack is currently a modular monolith built with NestJS, TypeScript, PostgreSQL, Redis, and TypeORM. Identity, sessions, verification, invites, and security audit concerns are delegated to the separate bakestake-identity service.

Current Architecture

• Runtime: Node.js 20
• Package manager: npm
• Application shape: modular monolith
• Identity boundary: external bakestake-identity service
• Data boundary in this repo: bakery operations, catalog, inventory, orders, customers, payments, analytics, outreach, media

Production Baseline Included

• Environment validation with fail-fast startup
• Secure bootstrap with Helmet, compression, request size limits, and environment-driven CORS
• Request correlation ids and structured request logging
• Redis centralized as shared infrastructure instead of ad hoc client construction
• Public-auth rate limiting on sensitive entry points
• Liveness, readiness, and dependency health endpoints
• Explicit production migration runners
• Docker, PM2, Nginx, and deployment notes
• Future extraction scaffold in microservices/

Architecture Docs

• docs/architecture.md
• docs/domain-boundaries.md
• docs/security.md
• docs/observability.md
• docs/idempotency.md
• docs/pos-sync.md
• docs/runbooks.md
• docs/incident-response.md
• docs/migrations.md
• docs/api-versioning.md
• docs/production-readiness-checklist.md

Health Endpoints

• GET /api/health/live
• GET /api/health/ready
• GET /api/health
• GET /api/health/dependencies/identity

Environment Files

• Development template: .env.example
• Production template: .env.production.example

Core variables:

• APP_NAME
• API_PREFIX
• HOST
• PORT
• NODE_ENV
• PUBLIC_APP_URL
• ENABLE_SWAGGER
• TRUST_PROXY
• REQUEST_BODY_LIMIT
• HELMET_ENABLED
• COMPRESSION_ENABLED
• ENABLE_REQUEST_LOGGING
• CORS_ALLOWED_ORIGINS
• CORS_ALLOW_CREDENTIALS
• CORS_ALLOW_ALL
• DATABASE_HOST
• DATABASE_PORT
• DATABASE_USERNAME
• DATABASE_PASSWORD
• DATABASE_NAME
• DATABASE_SSL
• DATABASE_POOL_SIZE
• DATABASE_CONNECTION_TIMEOUT_MS
• DATABASE_RETRY_ATTEMPTS
• DATABASE_RETRY_DELAY_MS
• REDIS_HOST
• REDIS_PORT
• REDIS_PASSWORD
• REDIS_DB
• REDIS_TLS
• IDENTITY_BASE_URL
• IDENTITY_INTERNAL_API_KEY
• IDENTITY_INTERNAL_SERVICE_NAME
• IDENTITY_SESSION_COOKIE_NAME
• IDENTITY_CSRF_COOKIE_NAME
• IDENTITY_REQUEST_TIMEOUT_MS
• IDENTITY_CACHE_TTL_SECONDS
• IDENTITY_REQUIRE_STEP_UP_FOR_PUBLISH
• JWT_SECRET
• JWT_EXPIRES_IN
• THROTTLE_AUTH_TTL_SECONDS
• THROTTLE_AUTH_LIMIT
• IDEMPOTENCY_TTL_HOURS
• ENABLE_QUEUE_WORKERS
• QUEUE_DEFAULT_ATTEMPTS
• QUEUE_DEFAULT_BACKOFF_MS
• METRICS_ENABLED
• OTEL_SERVICE_NAME
• STRIPE_WEBHOOK_SECRET

Local Development

Identity service first:

cd "/Users/surajmahapatra/Desktop/OUTREACH SECURITY "
npm install
cp .env.example .env
docker compose up -d postgres redis
npm run prisma:generate
npm run prisma:migrate:deploy
npm run prisma:seed
npm run dev

Then this backend:

cd "/Users/surajmahapatra/Desktop/OUTREACH BACKEND"
npm install
cp .env.example .env
npm run migration:run
npm run seed
npm run start:identity-local

start:identity-local runs the delegated backend on http://localhost:3002/api, enables local CORS for the UI, and applies pending migrations on boot.

Production-like Local Run

nvm use 20
npm ci
npm run build
npm run migration:run:prod
PORT=3002 npm run start:prod
curl -fsS http://127.0.0.1:3002/api/health/ready

To run migrations on boot intentionally:

RUN_MIGRATIONS_ON_BOOT=true npm run start:prod:safe

Docker

Development:

docker compose -f docker-compose.dev.yml up --build

Production-style compose:

docker compose up --build

The Docker image exposes a healthcheck against /api/health/live.

PM2

PM2 config is provided in ecosystem.config.cjs.

pm2 start ecosystem.config.cjs --env production
pm2 logs bakestake-backend

Migration Commands

Development TS runner:

npm run migration:run
npm run migration:revert

Compiled production runner:

npm run build
npm run migration:run:prod
npm run migration:revert:prod

Microservices Roadmap

The current backend should remain a monolith for now. The extraction staging area is in microservices/.

Best early extraction candidates:

• worker-service
• analytics-service

Later extraction candidates:

• notification-service
• email-service
• billing-service

Do not extract yet:

• catalog and inventory writes
• order creation and cancellation
• bakery settings and storefront publish workflow
• payment orchestration tied directly to orders

Those domains still share transactional consistency requirements and would become more fragile if split now.

Smoke Test

npm run test:smoke
SMOKE_BASE_URL=http://localhost:3002 npm run test:smoke

The backend seed creates the bakery, categories, and products. Authentication credentials come from the separate identity service seed.

Load Tests

K6_BASE_URL=http://localhost:3002 \
K6_BAKERY_SLUG=sweet-crumbs \
npm run loadtest:catalogue

K6_BASE_URL=http://localhost:3002 \
K6_BAKERY_SLUG=sweet-crumbs \
npm run loadtest:checkout

K6_BASE_URL=http://localhost:3002 \
K6_STRIPE_WEBHOOK_SECRET=whsec_local_development_secret \
npm run loadtest:webhooks

Deployment Notes

Detailed rollout and rollback guidance lives in docs/production-deployment.md.