A production-ready, fullstack e-commerce system built with modern technologies.
FastAPI · React · Flutter · PostgreSQL · Redis · Docker
A fullstack e-commerce platform designed with scalability, security, and developer experience as core principles. The system supports the complete purchase lifecycle — from product discovery and cart management through payment processing and shipment tracking — across web and mobile clients.
Built with an API-first architecture, the platform cleanly separates concerns between a high-performance Python backend, a modern React SPA, and a cross-platform Flutter mobile app, all orchestrated through Docker for consistent development and deployment environments.
┌─────────────────────────────────────────────────────────────────┐
│ Client Layer │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ React SPA │ │ Flutter App │ │
│ │ (TypeScript) │ │ (Dart) │ │
│ │ Vite + ShadCN │ │ Riverpod │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
└───────────┼──────────────────────┼──────────────────────────────┘
│ HTTPS / REST │
▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ API Gateway Layer │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ FastAPI (Uvicorn / Gunicorn) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │ │
│ │ │ Auth │ │ Products │ │ Orders │ │ Payments │ │ │
│ │ │ Routes │ │ Routes │ │ Routes │ │ Routes │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └────────────┘ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │ │
│ │ │ Cart │ │ Admin │ │ Webhooks │ │ Users │ │ │
│ │ │ Routes │ │ Routes │ │ Routes │ │ Routes │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
└───────────┬──────────────────────┬──────────────────────────────┘
│ │
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ PostgreSQL 15 │ │ Redis 7 │
│ (Primary Store) │ │ (Cache + Sessions) │
│ via Supabase │ │ Rate Limiting │
└──────────────────────┘ └──────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ External Services │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ Razorpay │ │ Twilio │ │ Shiprocket │ │
│ │ Payments │ │ OTP/SMS │ │ Shipping │ │
│ └──────────┘ └──────────┘ └──────────────┘ │
└──────────────────────────────────────────────┘
| Layer | Technology | Purpose |
|---|---|---|
| Backend | Python 3.11, FastAPI, SQLAlchemy 2.0 | REST API, business logic, ORM |
| Frontend | React 18, TypeScript, Vite, TailwindCSS | Single-page application |
| Mobile | Flutter 3.x, Dart, Riverpod | Cross-platform mobile app |
| Database | PostgreSQL 15 (Supabase) | Persistent data storage |
| Cache | Redis 7 | Rate limiting, session caching |
| Payments | Razorpay | Payment gateway integration |
| SMS/OTP | Twilio | OTP-based authentication |
| Shipping | Shiprocket | Order fulfillment & tracking |
| SMTP (aiosmtplib) | Transactional notifications | |
| DevOps | Docker, Docker Compose, Render | Containerized deployment |
| Monitoring | Sentry | Error tracking & performance |
- OTP-based passwordless authentication via SMS (Twilio)
- JWT access + refresh token rotation with blacklist support
- Rate-limited OTP requests (per-hour limits)
- Bcrypt password hashing for admin accounts
- Request ID middleware for distributed tracing
- Paginated product catalog with slug-based routing
- Rich product schema: images, specifications, MRP vs. selling price
- Admin CRUD operations with stock management
- Active/inactive product visibility control
- Persistent server-side cart for authenticated users
- Guest cart merge on login (seamless handoff)
- Real-time stock validation on add/update
- Quantity limits (max 10 per item)
- Stock reservation on order creation (prevents overselling)
- Stock commit on payment verification
- Auto-cancellation of expired unpaid orders (30-min TTL via background task)
- Order number generation with timestamp + random suffix
- Full order history with pagination
- Razorpay integration with server-side order creation
- Cryptographic signature verification
- Idempotent payment verification (safe retries)
- Automatic refund on cancellation
- Webhook support for async payment events
- Secure admin authentication (email/password + JWT)
- Order management (status updates, bulk operations)
- Analytics dashboard (revenue, order counts, daily trends)
- Product CRUD (create, update stock, toggle visibility)
- Shiprocket integration for shipment creation
- Shiprocket API integration for label generation
- Real-time shipment status tracking
- AWB number and courier assignment
- Tracking URL generation for customers
- Transactional email service (order confirmation, payment receipt, refund)
- SMS notifications for OTP and order updates
- Async, fire-and-forget notification delivery
├── backend/ # Python FastAPI application
│ ├── app/
│ │ ├── api/ # API route handlers
│ │ │ ├── deps.py # Dependency injection (auth, rate limiting)
│ │ │ └── v1/ # Versioned API endpoints
│ │ │ ├── auth.py # OTP send/verify, token refresh, logout
│ │ │ ├── products.py # Product listing & detail
│ │ │ ├── cart.py # Cart CRUD & merge
│ │ │ ├── orders.py # Order creation, listing, cancellation
│ │ │ ├── payments.py # Razorpay create/verify
│ │ │ ├── users.py # Profile & address management
│ │ │ ├── admin.py # Admin operations & analytics
│ │ │ └── webhooks.py # Razorpay & Shiprocket webhooks
│ │ ├── core/ # Core utilities
│ │ │ ├── config.py # Pydantic settings (env validation)
│ │ │ ├── security.py # JWT, OTP, password hashing
│ │ │ ├── middleware.py # Request ID middleware
│ │ │ ├── logging.py # Structured logging
│ │ │ ├── retry.py # Retry utilities for external APIs
│ │ │ └── order_state.py # Order state machine
│ │ ├── db/ # Database layer
│ │ │ ├── database.py # Async engine & session factory
│ │ │ ├── models.py # SQLAlchemy ORM models
│ │ │ └── migrations/ # Alembic migration scripts
│ │ ├── schemas/ # Pydantic request/response schemas
│ │ ├── services/ # Business logic services
│ │ │ ├── razorpay_service.py
│ │ │ ├── email_service.py
│ │ │ ├── shiprocket_service.py
│ │ │ └── twilio_sms.py
│ │ └── integrations/ # External API clients
│ │ ├── shiprocket.py
│ │ └── sms.py
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── gunicorn.conf.py
│ ├── alembic.ini
│ └── seed_db.py # Database seeding script
│
├── frontend/ # React TypeScript application
│ ├── client/
│ │ ├── App.tsx # Root component with routing
│ │ ├── pages/ # Page components
│ │ │ ├── Index.tsx # Home / product showcase
│ │ │ ├── Cart.tsx # Shopping cart
│ │ │ ├── Checkout.tsx # Checkout flow
│ │ │ ├── Login.tsx # OTP authentication
│ │ │ └── Account.tsx # User profile & orders
│ │ ├── components/ # Reusable UI components
│ │ │ ├── Header.tsx
│ │ │ ├── Footer.tsx
│ │ │ └── ui/ # ShadCN UI primitives
│ │ ├── context/ # React context providers
│ │ ├── hooks/ # Custom React hooks
│ │ └── lib/ # Utility functions
│ ├── server/ # SSR / BFF layer (Express)
│ ├── shared/ # Shared types (client ↔ server)
│ ├── Dockerfile
│ ├── vite.config.ts
│ └── package.json
│
├── mobile/ # Flutter mobile application
│ ├── lib/
│ │ ├── main.dart # App entry point
│ │ ├── core/ # Theme, routing, constants
│ │ ├── screens/ # Feature screens
│ │ │ ├── auth/
│ │ │ ├── home/
│ │ │ ├── product/
│ │ │ ├── cart/
│ │ │ ├── checkout/
│ │ │ ├── orders/
│ │ │ └── profile/
│ │ ├── providers/ # Riverpod state management
│ │ ├── services/ # API service layer
│ │ └── widgets/ # Reusable UI widgets
│ └── pubspec.yaml
│
├── infra/ # Infrastructure & deployment
│ ├── docker-compose.yml # Full stack orchestration
│ └── render.yaml # Render.com deployment config
│
├── docs/ # Documentation
│ ├── architecture.md # System design & decisions
│ └── api.md # API reference
│
├── .gitignore
└── README.md
The backend follows a clean layered architecture — routes handle HTTP concerns, services encapsulate business logic, and the database layer provides an async ORM abstraction. Each domain (auth, cart, orders, payments) is self-contained with its own router, schemas, and dependencies.
A two-phase stock management system prevents overselling in concurrent environments:
- Reserve — Stock is reserved (not deducted) when an order is created
- Commit — Reserved stock is committed (deducted) only after payment verification
- Release — If payment fails or the order expires, reserved stock is returned to the available pool
The application runs async background loops for:
- Order cleanup — Cancels unpaid orders after 30 minutes, releasing reserved stock
- Token cleanup — Purges expired JWT blacklist entries daily
All three clients (web, mobile, admin) consume the same versioned REST API (/api/v1), ensuring consistent behavior and enabling independent client development. The API is designed with proper:
- Request/response validation via Pydantic schemas
- Pagination on all list endpoints
- Idempotent payment verification
- Structured error responses
The entire stack is orchestrated via Docker Compose with health checks, service dependencies, and persistent volumes. Production deployment is configured for Render.com with auto-generated secrets.
- Docker & Docker Compose (recommended)
- Or individually: Python 3.11+, Node.js 18+, Flutter 3.2+
# Clone the repository
git clone https://github.com/pratheep-bit/ECOMMERCE-SITE-CKM.git
cd ECOMMERCE-SITE-CKM
# Copy environment template
cp backend/.env.example backend/.env
# Edit backend/.env with your credentials (Supabase, Razorpay, Twilio, etc.)
# Start all services
docker-compose -f infra/docker-compose.yml up --build
# Services will be available at:
# Backend API: http://localhost:8000
# Frontend: http://localhost:3000
# API Docs: http://localhost:8000/docs (dev mode only)Backend
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your configuration
uvicorn app.main:app --reload --port 8000Frontend
cd frontend
npm install
npm run dev
# Opens at http://localhost:5173Mobile
cd mobile
flutter pub get
flutter runSee backend/.env.example for the complete list. Key variables:
| Variable | Description |
|---|---|
DATABASE_URL |
PostgreSQL connection string (async) |
REDIS_URL |
Redis connection URL |
JWT_SECRET_KEY |
Secret for JWT signing |
RAZORPAY_KEY_ID |
Razorpay API key |
RAZORPAY_KEY_SECRET |
Razorpay API secret |
TWILIO_ACCOUNT_SID |
Twilio SMS account SID |
SUPABASE_URL |
Supabase project URL |
Interactive API docs are available at /docs (Swagger UI) and /redoc when running in development mode.
For a complete endpoint reference, see docs/api.md.
- Search & Filtering — Elasticsearch integration for product search
- Caching Layer — Redis-backed response caching for product catalog
- CI/CD Pipeline — GitHub Actions for automated testing and deployment
- Microservices Split — Extract payments and notifications into independent services
- WebSocket Notifications — Real-time order status updates
- Internationalization — Multi-language and multi-currency support
- Analytics Dashboard — Grafana + Prometheus for operational metrics
This project is built for educational and portfolio demonstration purposes.
Built with precision by Pratheep