🏏 Cricket Auction Platform

An open-source, IPL-style player auction system with real-time bidding

Experience the thrill of live player auctions — perfect for office cricket leagues, fantasy sports, or any team-building event!

Features

Real-time Bidding — WebSocket-powered live auctions with instant updates
Multi-Role System — Admin, Organizer, Auctioneer, Captain, Player, Spectator
Smart Timer — Auto-resets on bids, configurable duration
Live Dashboard — Track budgets, rosters, and bid history in real-time
Spectator Mode — Projector-ready full-screen view for audiences
Email Invitations — Automated invites via AWS SES (or configure your own SMTP)
Player Profiles — Photo uploads with skill ratings
Secure Auth — JWT-based authentication with magic link support
Docker Ready — One-command deployment with Docker Compose
Scalable — Redis-based coordination supports multiple workers/pods

Screenshots

Click to view screenshots

Event Dashboard

Multi-Role Selection

Login

Auction Completed Summary

Tech Stack

Layer	Technology
Backend	FastAPI, SQLAlchemy (async), PostgreSQL, Redis, ARQ
Frontend	Next.js 14 (App Router), TailwindCSS, Zustand
Storage	AWS S3 (or local uploads)
Email	AWS SES (configurable)
Infrastructure	Docker Compose, Traefik (TLS/Let's Encrypt)

Quick Start

Option 1: Full Docker Setup (Recommended)

This runs everything including PostgreSQL and Redis in Docker.

# 1. Clone the repository
git clone https://github.com/your-username/cricket-auction.git
cd cricket-auction

# 2. Copy environment file
cp .env.example .env

# 3. Start all services
docker compose up --build

# 4. Open http://localhost in your browser

Option 2: Use Your Own Database

If you have an existing PostgreSQL database and want to use it instead of Docker's:

# 1. Copy environment file
cp .env.example .env

# 2. Edit .env with your database connection
DATABASE_URL=postgresql+asyncpg://user:password@your-db-host:5432/auction_db

# 3. Start services (without db)
docker compose up --build backend frontend redis nginx worker

Option 3: Local Development (No Docker)

# Backend
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# Frontend (new terminal)
cd frontend
npm install
npm run dev

Note: You'll need PostgreSQL and Redis running locally or remotely.

Configuration

Environment Variables

Create a .env file in the root directory:

# ── App ──────────────────────────────────────────────────────────────────────
SECRET_KEY=your-super-secret-key-change-this
GODMODE_SECRET=testing-secret-for-dev-only

# ── Database ─────────────────────────────────────────────────────────────────
# Option A: Use Docker's PostgreSQL (default)
DATABASE_URL=postgresql+asyncpg://auction:auction@db:5432/auction

# Option B: Use your own PostgreSQL
# DATABASE_URL=postgresql+asyncpg://user:password@your-host:5432/your_db

# ── Redis ────────────────────────────────────────────────────────────────────
REDIS_URL=redis://redis:6379
# Or your own: REDIS_URL=redis://your-redis-host:6379

# ── Frontend URLs ────────────────────────────────────────────────────────────
NEXT_PUBLIC_API_URL=http://localhost/api
NEXT_PUBLIC_WS_URL=ws://localhost/api/auction/ws

# ── AWS SES (Email) - Optional ───────────────────────────────────────────────
# Leave empty to disable email features
AWS_MAIL_ACCESS_KEY_ID=
AWS_MAIL_SECRET_ACCESS_KEY=
AWS_REGION=ap-south-1
EMAIL_FROM=auction@yourdomain.com

# ── AWS S3 (Profile Photos) - Optional ───────────────────────────────────────
# Leave empty to use local file storage
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_BUCKET_NAME=

Database Migrations

After starting the services, run migrations:

# With Docker
docker compose exec backend alembic upgrade head

# Without Docker
cd backend && alembic upgrade head

Seed Test Data (Optional)

docker compose exec backend python seed_players.py

Production Deployment

Using Docker Compose + Traefik (Recommended)

# 1. Create production env file
cp .env.prod.example .env.prod

# 2. Configure production values (REQUIRED changes marked)
nano .env.prod

Required changes in .env.prod:

# Your domain (must point to your server IP)
PUBLIC_DOMAIN=auction.yourdomain.com
TRAEFIK_ACME_EMAIL=admin@yourdomain.com

# Generate strong secrets!
SECRET_KEY=$(openssl rand -hex 32)
GODMODE_SECRET=$(openssl rand -hex 32)
POSTGRES_PASSWORD=$(openssl rand -hex 16)

# 3. Deploy
docker compose -f docker-compose.prod.yml --env-file .env.prod up --build -d

# 4. Run migrations
docker compose -f docker-compose.prod.yml exec backend alembic upgrade head

Using External Database

To use an external PostgreSQL (e.g., AWS RDS, Supabase, Neon):

Remove the db service from docker-compose.prod.yml

Update DATABASE_URL in .env.prod:

DATABASE_URL=postgresql+asyncpg://user:password@your-rds-endpoint:5432/auction

Remove db from depends_on in backend, worker, and migrator services

User Roles

Role	Capabilities
Admin	Create events, assign organizers/auctioneers, manage allowed email domains
Organizer	Configure event settings, add players, create teams, assign captains
Auctioneer	Start/pause auction, pick players, hammer sales, finish event
Captain	Place bids, view budget & roster, bookmark players
Player	Complete profile (photo, ratings), view personal dashboard
Spectator	Watch live auction, view standings and history

Auction Flow

┌─────────────────────────────────────────────────────────────────┐
│  1. ADMIN creates event → assigns ORGANIZER                     │
├─────────────────────────────────────────────────────────────────┤
│  2. ORGANIZER sets up event:                                    │
│     • Configure budget, max players per team                    │
│     • Add players (by email domain)                             │
│     • Create teams, assign CAPTAINS                             │
│     • Mark event as "Ready"                                     │
├─────────────────────────────────────────────────────────────────┤
│  3. System sends email invitations to all participants          │
├─────────────────────────────────────────────────────────────────┤
│  4. AUCTIONEER starts auction:                                  │
│     • Pick player (random or manual)                            │
│     • Timer starts (180 seconds default)                        │
├─────────────────────────────────────────────────────────────────┤
│  5. CAPTAINS bid in real-time:                                  │
│     • Timer resets on each bid                                  │
│     • Max bid increment: min(50% of current, 5% of budget)      │
├─────────────────────────────────────────────────────────────────┤
│  6. Timer expires → Player SOLD or UNSOLD                       │
│     • Unsold players can be re-auctioned                        │
├─────────────────────────────────────────────────────────────────┤
│  7. AUCTIONEER finishes auction → Summary displayed             │
└─────────────────────────────────────────────────────────────────┘

WebSocket Events

Connect to: ws://your-domain/api/auction/ws/{eventId}?token=<jwt>

Event	Description
`auction_state`	Full state snapshot on connect
`player_up`	New player put up for auction
`new_bid`	A captain placed a bid
`timer_tick`	Timer countdown (every second)
`player_sold`	Player sold to a captain
`player_unsold`	Player went unsold
`auction_paused`	Auctioneer paused the auction
`auction_resumed`	Auctioneer resumed the auction
`auction_completed`	Auction finished

Testing & Development

God Mode (Dev Only)

Instantly log in as any user without password:

http://localhost/auth/login?godmode=YOUR_GODMODE_SECRET&email=user@example.com

API Documentation

Swagger UI: http://localhost/api/docs
ReDoc: http://localhost/api/redoc

Running Tests

# Backend tests
cd backend
pytest

# Frontend tests
cd frontend
npm test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Inspired by IPL player auctions
Built with ❤️ for cricket lovers

Contact & Support

A project by Techiebutler

Have questions? Need help?

Email: support@techiebutler.com

⭐ Star this repo if you find it useful!

Report Bug · Request Feature

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
backend		backend
frontend		frontend
nginx		nginx
readme_asset		readme_asset
scripts		scripts
.env.example		.env.example
.env.prod.example		.env.prod.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

🏏 Cricket Auction Platform

Features

Screenshots

Event Dashboard

Multi-Role Selection

Login

Auction Completed Summary

Tech Stack

Quick Start

Option 1: Full Docker Setup (Recommended)

Option 2: Use Your Own Database

Option 3: Local Development (No Docker)

Configuration

Environment Variables

Database Migrations

Seed Test Data (Optional)

Production Deployment

Using Docker Compose + Traefik (Recommended)

Using External Database

User Roles

Auction Flow

WebSocket Events

Testing & Development

God Mode (Dev Only)

API Documentation

Running Tests

Contributing

License

Acknowledgments

Contact & Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages