Dress Commerce Enterprise API

A production-oriented FastAPI backend for dresses, apparel and fashion e-commerce. It is designed as a modular monolith that can later be split into catalog, inventory, order, payment and customer services.

Major capabilities

• JWT access and refresh tokens with revocation
• Argon2 password hashing
• RBAC for customer, administrator, catalog manager, warehouse manager and support
• Categories, brands, products and fashion-specific size/color/SKU variants
• Variant-level prices, barcodes and stock
• On-hand, reserved and available inventory with movement ledger
• Product search and filters by category, brand, gender, size, color and price
• Customer addresses, carts and wishlists
• Percentage and fixed-value coupons
• Tax, shipping and discount calculations
• Idempotent checkout and payment operations
• COD, card and UPI payment flows with a safe mock provider
• Immutable order-item snapshots
• Controlled order-state transitions
• Verified-purchase reviews
• Return, receipt, restocking and refund workflow
• Administration dashboard, low-stock report and audit logs
• PostgreSQL, Alembic, Docker Compose and automated tests
• Swagger, ReDoc and exported OpenAPI JSON

Architecture

Client applications
       |
       v
FastAPI /api/v1
       |
       +-- Authentication and RBAC
       +-- Catalog and variants
       +-- Inventory ledger
       +-- Cart and wishlist
       +-- Pricing and promotions
       +-- Orders and payments
       +-- Reviews and returns
       +-- Analytics and audit
       |
       v
SQLAlchemy -> PostgreSQL

API documentation

After starting the application:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json
• Health: http://localhost:8000/api/v1/health
• Readiness: http://localhost:8000/api/v1/ready

The repository also includes a generated openapi.json file.

Docker setup

Copy-Item .env.example .env
docker compose up --build

Seed the demonstration records:

docker compose exec api python -m scripts.seed

Stop the application:

docker compose down

Remove the database volume as well:

docker compose down -v

Local Windows setup

Create and activate a virtual environment:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Create local environment settings:

Copy-Item .env.example .env

For SQLite development, change this value inside .env:

DATABASE_URL=sqlite:///./dress_api.db

Run migrations and seed data:

alembic upgrade head
python -m scripts.seed

Start the API:

uvicorn app.main:app --reload

Demo accounts

All seeded accounts use Password@123.

Role	Email
Administrator	admin@dress.local
Catalog manager	catalog@dress.local
Warehouse manager	warehouse@dress.local
Customer support	support@dress.local
Customer	customer@dress.local

Typical workflow

1. Log in as the administrator or catalog manager.
2. Create categories, brands and products.
3. Create size/color variants with unique SKUs.
4. Update inventory using the inventory-adjustment endpoint.
5. Register or log in as a customer.
6. Add a shipping address and cart items.
7. Validate an optional coupon.
8. Checkout with an Idempotency-Key header.
9. Confirm a card/UPI payment using another idempotency key, or select COD.
10. Move the order through processing, packed, shipped and delivered.
11. Submit a verified-purchase review or return request.
12. Receive and refund the return through a support/admin account.

Idempotency

Checkout and online payment endpoints require an Idempotency-Key header. Retrying the same operation with the same key returns the existing resource instead of creating a duplicate.

Example:

curl -X POST http://localhost:8000/api/v1/orders/checkout \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-user-42-0001" \
  -d '{"address_id":1,"payment_method":"card","coupon_code":"WELCOME10"}'

Payment integration

The included card/UPI flow is a deterministic mock provider for development and testing. For production, replace the payment endpoint internals with a PCI-compliant gateway adapter such as Razorpay or Stripe and verify signed webhooks before changing order payment state.

Database migrations

alembic upgrade head

Create a future migration after changing models:

alembic revision --autogenerate -m "describe the schema change"
alembic upgrade head

Tests

pytest

The lifecycle test covers:

• registration and authentication
• administrator RBAC
• category, brand, product and variant creation
• stock initialization
• coupon creation
• customer address and cart
• idempotent checkout
• successful payment
• complete order lifecycle
• verified-purchase review
• return receipt and refund
• analytics dashboard

Main endpoint groups

Area	Base paths
Authentication	/api/v1/auth/*
Users and addresses	/api/v1/users, /api/v1/addresses/*
Catalog	/api/v1/catalog/*
Cart	/api/v1/cart/*
Wishlist	/api/v1/wishlist/*
Orders and payments	/api/v1/orders/*
Reviews	/api/v1/products/{id}/reviews
Returns	/api/v1/returns/*
Administration	/api/v1/admin/*
Health	/api/v1/health, /api/v1/ready

Production hardening checklist

Before a public launch:

• Replace all development secrets.
• Use managed PostgreSQL with backups and point-in-time recovery.
• Place the API behind TLS, a reverse proxy and a web application firewall.
• Add Redis-backed distributed rate limiting.
• Add signed payment webhooks and reconciliation jobs.
• Use an object-storage service and signed URLs for product images.
• Add background workers for email, invoices, stock alerts and exports.
• Add OpenTelemetry traces, centralized logs and error monitoring.
• Add database read replicas only after measuring a real need.
• Add load, security, recovery and concurrency tests.

Project structure

app/
  config.py
  database.py
  dependencies.py
  main.py
  models.py
  schemas.py
  security.py
  services.py
  routes/
    admin.py
    auth.py
    catalog.py
    health.py
    shop.py
    users.py
migrations/
scripts/
tests/
Dockerfile
docker-compose.yml
openapi.json