SwiftDrop — Flash Sale Platform

Bitcode 2026 | Full-Stack Engineering Challenge

Stack

Layer	Technology
Frontend	Vue.js 3 + Pinia + Vue Router
Backend	Python 3.12 + FastAPI + SQLAlchemy (async)
Database (relational)	PostgreSQL (via asyncpg)
Database (NoSQL)	MongoDB (via Motor)
Proxy + Rate Limiting	Nginx
Containerization	Docker + Docker Compose

---

Project Structure

swiftdrop/
├── backend/
│   ├── app/
│   │   ├── core/             # config, security (JWT/bcrypt), dependencies
│   │   ├── db/               # postgres.py, mongo.py connections
│   │   ├── middlewares/      # error_handler, rate_limit, logging_middleware
│   │   ├── models/           # SQLAlchemy ORM: user, event, item, order
│   │   ├── schemas/          # Pydantic: auth, event, item, order, review
│   │   ├── repositories/     # All DB queries (postgres + mongo)
│   │   ├── services/         # Business logic: auth, event, item, purchase, review
│   │   ├── routers/          # Thin route handlers
│   │   │   └── admin/        # Admin-only routes
│   │   └── utils/            # scheduler.py (event transitions), seed.py
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── common/       # Navbar, CountdownTimer, StatusBadge
│   │   │   └── reviews/      # RatingStars, CommentSection
│   │   ├── views/
│   │   │   ├── auth/         # LoginView, RegisterView
│   │   │   ├── customer/     # EventList, EventDetail, PurchaseConfirm, Orders, Profile
│   │   │   └── admin/        # Dashboard, EventCreate, EventEdit, Catalog, Users
│   │   ├── stores/           # Pinia: auth.js, events.js
│   │   ├── services/         # Axios: api.js, auth, events, purchase, reviews
│   │   └── router/           # Vue Router with auth guards
│   └── Dockerfile
├── nginx/
│   └── nginx.conf            # Rate limiting + reverse proxy
├── docker-compose.yml
└── .env                      # (copy from .env.example)

---

Setup & Run

1. Copy environment file

cp .env.example .env

Edit .env and fill in your PostgreSQL URL and MongoDB URI:

DATABASE_URL=postgresql+asyncpg://user:password@host:5432/swiftdrop
MONGO_URI=mongodb+srv://...  # or your local URI
MONGO_DB_NAME=swiftdrop_reviews
SECRET_KEY=your-secret-key-here

2. Start all services

docker-compose up --build

• Frontend: http://localhost
• API Docs: http://localhost/api/docs

3. Seed the database

docker-compose exec api python -m app.utils.seed

This creates:

• Admin account: admin@swiftdrop.com / Admin@1234
• 3 catalog items (Electronics, Home Appliances)
• 1 sample event going live in 2 minutes

---

Development (without Docker)

Backend — using venv

One-command setup (recommended):

make venv

Or manually:

python3 -m venv backend/venv
source backend/venv/bin/activate        # Windows: backend\venv\Scripts\activate
pip install --upgrade pip
pip install -r backend/requirements.txt

Copy and fill env file:

cp .env.example backend/.env            # fill in DATABASE_URL, MONGO_URI, SECRET_KEY

Run dev server:

source backend/venv/bin/activate
cd backend
uvicorn app.main:app --reload --port 8000

Or via Makefile:

make backend

Seed database:

make seed

Frontend

cd frontend
npm install
npm run dev  # runs on :5173, proxies /api to :8000

Or via Makefile:

make frontend

---

Key Environment Variables

Variable	Description
DATABASE_URL	PostgreSQL async URL (postgresql+asyncpg://...)
MONGO_URI	MongoDB connection URI
MONGO_DB_NAME	MongoDB database name (default: swiftdrop_reviews)
SECRET_KEY	JWT signing secret (use a long random string)
ALGORITHM	JWT algorithm (default: HS256)
ACCESS_TOKEN_EXPIRE_MINUTES	Token TTL (default: 60)
ALLOWED_ORIGINS	Comma-separated CORS origins

---

Database Schema

PostgreSQL (relational)

Table	Purpose
users	Customers + Admins
events	Sale events with status (locked/live/closed/sold_out)
item_catalog	Reusable master item library
event_items	Event-specific item assignment (price + stock)
orders	Purchase records

Item reuse: Admins create items once in item_catalog, then assign them to any number of events via event_items with per-event pricing and stock.

MongoDB (NoSQL)

Collection	Purpose
reviews	Per-item ratings (1–5 stars) + comments
event_comments	Event discussion with nested replies

---

Concurrency Design

The purchase endpoint uses an atomic SQL UPDATE to prevent oversell:

UPDATE event_items
SET stock_remaining = stock_remaining - 1
WHERE id = :event_item_id AND stock_remaining > 0

• If rowcount = 1 → stock reserved, order created (same transaction)
• If rowcount = 0 → sold out, immediate 409 response
• Nginx rate limits purchase endpoint to 5 req/s per IP (burst 10)
• FastAPI SlowAPI adds application-level rate limiting as a second layer

---

API Endpoints Summary

Auth

Method	Path	Description
POST	/api/v1/auth/register	Register customer
POST	/api/v1/auth/login	Login, get JWT
POST	/api/v1/auth/logout	Logout
PUT	/api/v1/auth/password	Change password

Events (Customer)

Method	Path	Description
GET	/api/v1/events	List all events
GET	/api/v1/events/{id}	Event detail + items + stock

Purchase

Method	Path	Description
POST	/api/v1/purchase/{event_item_id}	Initiate (atomic reserve)
POST	/api/v1/purchase/{order_id}/confirm	Confirm order
POST	/api/v1/purchase/{order_id}/cancel	Cancel + release stock

Profile

Method	Path	Description
GET	/api/v1/profile	View profile
PUT	/api/v1/profile	Update display name
GET	/api/v1/profile/orders	Order history

Reviews (MongoDB)

Method	Path	Description
POST	/api/v1/reviews/items/{item_id}	Add/update rating
GET	/api/v1/reviews/items/{item_id}	Get reviews
GET	/api/v1/reviews/items/{item_id}/summary	Average rating
POST	/api/v1/reviews/events/{event_id}/comments	Add comment
GET	/api/v1/reviews/events/{event_id}/comments	Get comments
POST	/api/v1/reviews/comments/{comment_id}/replies	Reply to comment

Admin

Method	Path	Description
POST	/api/v1/admin/events	Create event
PUT	/api/v1/admin/events/{id}	Edit locked event
POST	/api/v1/admin/events/{id}/open	Force open
POST	/api/v1/admin/events/{id}/close	Force close
GET	/api/v1/admin/events/dashboard	Dashboard stats
GET	/api/v1/admin/items	List catalog
POST	/api/v1/admin/items	Create catalog item
GET	/api/v1/admin/users	List customers
POST	/api/v1/admin/users/{id}/deactivate	Deactivate user
POST	/api/v1/admin/users/{id}/activate	Reactivate user