• Overview
• Key Engineering Highlights
• Features
• Architecture
• Tech Stack
• Project Structure
• Getting Started
• Docker
• Environment Variables
• API Reference
• Key Engineering Decisions
• Concurrency Handling
• Security
• Limitations & Future Improvements
• Deployment
• Author

This API simulates the backend of a multi-vendor marketplace. It handles product listings, order placement, stock management, and order lifecycle tracking across two user roles — buyers and sellers.

The core engineering challenge: two buyers attempting to purchase the last available unit simultaneously. This is solved using PostgreSQL transactions combined with row-level locking (SELECT FOR UPDATE), ensuring only one order succeeds and stock never goes negative.

Designed to handle real-world edge cases like concurrent purchases of limited stock, ensuring data consistency under concurrent load.

• Prevents overselling using PostgreSQL transactions and row-level locking (SELECT FOR UPDATE)
• Ensures atomic order creation across multiple tables (orders, order_items, products)
• Handles concurrent users safely with database-level consistency guarantees
• Optimized queries using JOINs, indexing, and pagination (avoids N+1 problems)

• JWT-based authentication and role-based access control (buyer/seller)
• Transaction-safe order creation with stock validation
• Concurrency handling using PostgreSQL row-level locking (SELECT FOR UPDATE)
• Product and inventory management for multi-vendor workflows
• Optimized queries using JOINs, pagination, and indexing
• Rate limiting and request validation for API reliability

High-level backend architecture illustrating how requests are processed through the system and how transactional operations ensure data consistency.

The system follows a layered structure:

• Client (API / Postman) sends HTTP requests
• Express server handles routing, middleware, and request lifecycle
• Controllers & Services manage business logic and coordinate operations
• PostgreSQL database ensures data integrity using transactions and row-level locking

Key focus:

• Transaction-safe operations across multiple tables
• Concurrency control using SELECT FOR UPDATE
• Consistent state management during concurrent requests

src/
├── app.ts
├── config/
│   └── db.ts
├── controllers/
├── services/
├── routes/
├── middlewares/
└── utils/

• Node.js 18+
• PostgreSQL 15+
• npm

git clone https://github.com/TirthWillLearn/Order-Management-API.git
cd Order-Management-API
npm install
cp .env.example .env
npm run dev

docker build -t order-api .
docker run --env-file .env -p 10000:10000 order-api

PORT=10000
DB_HOST=your_db_host
DB_PORT=5432
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_NAME=order_management
JWT_SECRET=your_jwt_secret
NODE_ENV=development

• POST /auth/register
• POST /auth/login

• GET /products
• POST /products (seller)

• POST /orders (transactional)
• GET /orders
• GET /orders/:id
• PATCH /orders/:id/status

• Transactions ensure atomic operations across multiple tables
• SELECT FOR UPDATE prevents race conditions during stock updates
• price_at_time preserves historical pricing
• Separate orders and order_items for proper relational modeling

Without locking:

• Multiple users read same stock → overselling

With locking:

• Row is locked → second request waits → correct stock maintained

• bcrypt password hashing
• JWT authentication
• Rate limiting (100 req / 15 min)
• Helmet security headers
• Environment variable protection

• Single-instance deployment (no horizontal scaling yet)
• Can add Redis caching for performance
• Can introduce job queues for async processing
• Can scale with load balancers and distributed systems

• API: Render
• DB: AWS RDS / Render DB
• Docker: Docker Hub

Tirth Patel

GitHub: https://github.com/TirthWillLearn
LinkedIn: https://www.linkedin.com/in/tirth-k-patel/
Portfolio: https://tirthdev.in