When learning backend development, most projects stop at CRUD APIs.
I wanted to go a step further and build a realistic ecommerce backend—one that follows industry practices, not shortcuts.
This blog walks through what I built, why I built it that way, and the key backend concepts involved.
Project Goal
To design a secure, scalable ecommerce backend that handles:
- Authentication
- Cart management
- Checkout flow
- Orders
- Payments
- Stock consistency
- Password recovery
All while following real-world backend design principles.
Tech Stack
- FastAPI – high-performance Python API framework
- SQLAlchemy – ORM for database modeling
- PostgreSQL – relational database
- Alembic – database migrations
- JWT – authentication
- bcrypt – password hashing
Authentication & Security
Passwords are never stored in plain text.
Passwords are hashed using bcrypt
JWT is used for authentication
Password recovery is handled via secure, time-bound reset tokens
No password is ever decrypted or sent back to users
Password recovery is implemented by resetting, not revealing passwords.
Cart Design (Temporary State)
The cart is designed as a mutable, temporary state:
- Users can add, update, or remove items
- Only one active cart per user
- Prices are snapshotted at the time of adding to cart
- This prevents price mismatch issues during checkout.
Checkout (State Transition)
Checkout is a critical boundary:
- Converts a cart into an immutable order
- Validates stock
- Calculates final price
- Creates a PENDING order
- Cart represents intent.
- Checkout represents commitment.
Orders (Immutable Records)
Orders are treated as financial records:
- Created only via checkout
- Read-only for users
- Status-based lifecycle: PENDING → PAID → CANCELLED
- This ensures auditability and consistency.
Payments (Asynchronous & Safe)
Payments are handled separately from checkout:
- Payment intents are created for orders
- Payments are confirmed asynchronously
- Stock is reduced only after payment success
This avoids overselling and handles real payment gateway behavior.
Stock Management
Stock updates are protected using row-level locking to avoid race conditions during concurrent purchases.
Stock is reduced only after confirmed payment—not during checkout.
API Documentation
Swagger (OpenAPI) is fully integrated:
- Cleanly grouped APIs
- Request & response schemas
- JWT authorization support
- Ready for frontend or third-party integration
Database Migrations
- All schema changes are managed via Alembic migrations
- No manual DB edits
- Reproducible environments
- Safe schema evolution
What I Learned
- Why carts and orders must be separate
- Why payments must be asynchronous
- Why passwords must be irreversible
- How ORM relationships fail if not symmetric
- How real-world ecommerce systems prevent overselling
Source Code
The complete project is available on GitHub:
https://github.com/sanjay-dot/Ecommerce
Final Thoughts
This project helped me move from API writing to system thinking.
If you’re learning backend development, I highly recommend building projects that:
- model real workflows
- enforce correct state transitions
- prioritize security from day one
