MedKit Store

Production-style full-stack commerce system for configuring and checking out medical kits with inventory-safe order flow, Stripe Checkout, CI validation, load-test evidence, and protected production observability.

Customers can configure kits, get live Redis-backed quotes, create authenticated orders, and enter Stripe Checkout. The backend is designed around correctness under concurrent demand: stock is reserved atomically before checkout, Stripe webhooks are idempotent, and integration tests verify that simultaneous checkout attempts cannot oversell low-stock inventory.

Live System

Surface	Link
Storefront	medkit-store.vercel.app
API readiness	medical-kit-store-api.onrender.com/ready
CI workflow	GitHub Actions

Preview

Storefront	Kit builder	Orders

Engineering Evidence

Area	Evidence
Concurrency correctness	Integration tests cover atomic stock reservation and concurrent checkout oversell protection
Payments reliability	Stripe checkout webhooks are idempotent for completed and expired sessions
Local load testing	Quote scenario handled 27,717 requests in 30s at 0% failure, p95 45.82 ms
Production sanity load	Render quote-only check handled 482 requests at 0% failure, p95 77.43 ms
Production readiness	/ready checks MongoDB and Redis; protected /metrics exposes request counts, status codes, route timing, and latency percentiles

Highlights

• Next.js storefront with product configuration, live quote updates, auth, order creation, and checkout result pages
• Express API with JWT auth, Zod validation, MongoDB persistence, Redis caching, and Stripe Checkout integration
• Atomic inventory reservation before checkout session creation
• Idempotent Stripe webhook handling for completed and expired sessions
• Production-style request tracing, JSON request logs, readiness checks, and request latency metrics
• Integration tests that cover checkout authorization, inventory reservation, webhook behavior, and concurrent oversell protection
• Repeatable benchmark and load-test scripts for API latency and throughput

Architecture

frontend/ Next.js app
  |
  | REST API calls
  v
backend/ Express API
  |-- MongoDB: users, products, orders
  |-- Redis: product and quote cache
  `-- Stripe: Checkout sessions and webhooks

Deployment is split by service:

Component	Runtime
Frontend	Vercel-hosted Next.js app
Backend	Render-hosted Express API
Database	MongoDB Atlas
Cache	External Redis
Payments	Stripe test mode

See DEPLOYMENT.md for the deployment environment contract.

Project Structure

backend/       Express API, data models, checkout workflow, tests, perf scripts
frontend/      Next.js storefront and order pages
DEPLOYMENT.md  Production deployment notes

Detailed service docs:

• Backend README
• Frontend README

Run Locally

Start MongoDB and Redis:

brew services start mongodb-community
brew services start redis

Start the backend:

cd backend
cp .env.example .env
npm install
npm run seed
npm run dev

Start the frontend in another terminal:

cd frontend
cp .env.example .env.local
npm install
npm run dev

Open http://localhost:3000.

Validation

Backend:

cd backend
npm test
npm run benchmark -- --url http://127.0.0.1:4000 --iterations 200 --warmup 20
npm run load:test -- --url http://127.0.0.1:4000 --scenario quote --duration 30 --concurrency 20

Production smoke test:

cd backend
API_BASE_URL=https://your-render-api.onrender.com \
FRONTEND_URL=https://your-vercel-app.example.com \
npm run smoke:prod

Frontend:

cd frontend
npm run lint
npm run build

If macOS rejects the native Next.js SWC binary, use the compatibility scripts in the frontend README.

Production Readiness

The backend includes production-style observability in addition to correctness and performance checks:

• x-request-id on every response, with client-provided IDs preserved
• JSON request logs and centralized 5xx error logs for request tracing
• /health for liveness and /ready for MongoDB/Redis dependency readiness
• /metrics for in-memory request counts, status codes, latency percentiles, route timing, and recent slow requests

/metrics can be protected with METRICS_TOKEN in deployed environments.

Latest verified production observability check: 2026-07-07

Check	Result
Render API /metrics without token	401
Render API /metrics with METRICS_TOKEN	passed
Metrics payload includes request counters, status codes, route timing, and latency percentiles	passed
Metrics payload excludes request bodies, auth tokens, and customer data	passed by implementation

Performance Snapshot

Local run on 2026-07-07 with Node.js v24.4.1, macOS arm64, local MongoDB, local Redis, and the backend listening on 127.0.0.1:4011.

Benchmark command:

cd backend
npm run benchmark -- --url http://127.0.0.1:4011 --iterations 1000 --warmup 100

Benchmark	Requests	Failure rate	RPS	P50	P95
Cached product read	1000	0%	1870.61	0.43 ms	0.90 ms
Cached quote	1000	0%	1064.21	0.63 ms	1.95 ms

Load-test commands:

npm run load:test -- --url http://127.0.0.1:4011 --scenario quote --duration 30 --concurrency 20
npm run load:test -- --url http://127.0.0.1:4011 --scenario mixed-read --duration 30 --concurrency 20
npm run load:test -- --url http://127.0.0.1:4011 --scenario order-create --duration 15 --concurrency 10

Scenario	Duration	Concurrency	Requests	Failure rate	RPS	P50	P95
Quote	30s	20	27717	0%	923.39	16.46 ms	45.82 ms
Mixed read	30s	20	30862	0%	1028.37	13.46 ms	45.62 ms
Order create	15s	10	9586	0%	638.75	14.16 ms	26.00 ms

order-create writes persistent test orders, so run it against a disposable local or staging database. Live Stripe Checkout is intentionally excluded from load tests; checkout oversell protection is covered by the integration suite.

Production Load Sanity Check

The deployed API was also verified with a deliberately light quote-only load run on Render's free tier. This is not a full production stress test; it avoids write-heavy endpoints and Stripe Checkout so it does not flood the free backend, database, or Redis plan.

Command:

cd backend
npm run load:test -- \
  --url https://medical-kit-store-api.onrender.com \
  --scenario quote \
  --duration 10 \
  --concurrency 3

Latest verified run: 2026-07-07

Scenario	Duration	Concurrency	Requests	Failure rate	RPS	P50	P95	Max
Production quote sanity	10s	3	482	0%	48.02	60.44 ms	77.43 ms	203.53 ms

Production Smoke Test

The production smoke script validates a deployed API without requiring direct access to Render, Vercel, MongoDB Atlas, Redis, or Stripe dashboards.

cd backend
API_BASE_URL=https://your-render-api.onrender.com \
FRONTEND_URL=https://your-vercel-app.example.com \
npm run smoke:prod

Latest verified deployment smoke test: 2026-07-07

Check	Result
Vercel frontend https://medkit-store.vercel.app	200
Render API https://medical-kit-store-api.onrender.com/ready	200
Active product catalog	passed
Quote creation	passed
Temporary user registration	passed
Authenticated order creation	passed

It checks:

• frontend HTML returns 200 when FRONTEND_URL is provided
• backend /ready reports MongoDB and Redis as up
• active product catalog is not empty
• POST /api/quote returns a positive total
• temporary smoke user registration returns a JWT
• authenticated POST /api/orders creates an order matching the quote

The script writes a temporary user and order, so run it against production only when test-mode data is acceptable. Stripe Checkout session creation is skipped by default; add -- --checkout only when Stripe test keys and redirect URLs are configured and you want to verify the Checkout redirect path.

Backend Correctness Focus

The backend is designed around inventory correctness, not just CRUD endpoints. Checkout claims an order, reserves stock atomically, invalidates affected caches, and rolls the order back if checkout setup fails. Tests verify that simultaneous checkout requests cannot reserve more inventory than exists and that Stripe webhooks are idempotent.

The performance scripts intentionally avoid live Stripe calls. They measure repeatable API paths such as cached product reads, quote generation, and authenticated order creation. Checkout oversell protection is verified in the integration suite with Stripe stubbed.