A web-based Lucky Wheel application developed with FastAPI, JavaScript, and SQLite. The system allows administrators to manage rewards, configure winning probabilities, customize the wheel appearance, and provide an engaging user experience with animations and sound effects.

Features

User Features

Interactive spin wheel
Smooth spinning animations
Sound effects during wheel rotation
Winner notification modal
Reward description display
Responsive user interface
Customizable page title
Customizable background color

Admin Features

Create, edit, and delete rewards
Configure reward probabilities
Manage reward descriptions
Configure wheel page title
Customize wheel appearance
Manage reward types
Real-time reward management

Supported Reward Types

The system supports three reward categories:

Reward Type	Description
Empty	No reward
Discount Code	Promotional discount code
LiveCoin (LC)	Virtual currency reward

Technology Stack

Backend

Python 3.10+
FastAPI
SQLAlchemy
Alembic
SQLite

Frontend

HTML5
CSS3
JavaScript (Vanilla JS)
Dana Font

Development Tools

Git
Uvicorn

Project Structure

spin-wheel/
│
├── backend/
│   ├── alembic/
│   ├── api/
│   │   ├── admin.py
│   │   └── user.py
│   │
│   ├── app/
│   ├── core/
│   ├── logs/
│   ├── services/
│   │
│   ├── main.py
│   ├── schemas.py
│   ├── config.py
│   ├── requirements.txt
│   └── spinwheel.db
│
├── frontend/
│   ├── assets/
│   │   ├── css/
│   │   └── fonts/
│   │
│   ├── js/
│   │   ├── admin.js
│   │   └── api.js
│   │
│   ├── admin.html
│   └── index.html
│
└── README.md

Installation

1. Clone the Repository

git clone <repository-url>
cd spin-wheel

2. Create a Virtual Environment

Windows

python -m venv venv
venv\Scripts\activate

Linux / macOS

python3 -m venv venv
source venv/bin/activate

3. Install Backend Dependencies

cd backend
pip install -r requirements.txt

4. Configure Environment Variables

Create a .env file inside the backend directory if required.

Example:

DATABASE_URL=sqlite:///spinwheel.db

5. Run Database Migrations

alembic upgrade head

6. Start Backend Server

uvicorn main:app --reload

Backend API:

http://127.0.0.1:8000

Swagger Documentation:

http://127.0.0.1:8000/docs

7. Start Frontend

Serve the frontend application on port 3000.

Example:

python -m http.server 3000

Frontend URL:

http://localhost:3000/index.html
http://localhost:3000/admin.html

API Endpoints

User APIs

Get Rewards

GET /user/items

Spin the Wheel

POST /user/spin

Example Response:

{
  "id": 1,
  "reward_type": "DISCOUNT_CODE",
  "title": "20% Discount",
  "description": "Get 20% off on your next purchase.",
  "probability": 15
}

Admin APIs

Get Rewards

GET /admin/items

Create Reward

POST /admin/items

Update Reward

PUT /admin/items/{id}

Delete Reward

DELETE /admin/items/{id}

Reward Probability System

Each reward has a configurable probability value.

The winner is selected using a weighted random selection algorithm.

Example:

Reward	Probability
Empty	50
Discount Code	30
LiveCoin	20

Higher values increase the chance of winning that reward.

Customization Options

The admin panel allows configuration of:

Wheel page title
Background color
Reward descriptions
Reward probabilities
Reward types
Wheel appearance

User Experience Enhancements

Wheel spinning animation
Sound effects
Winner modal popup
Reward details display
Modern Persian typography using Dana Font

Future Improvements

Authentication & Authorization
User Accounts
Spin History
Analytics Dashboard
Campaign Management
Multi-language Support
Docker Deployment

Security Recommendations

For production environments:

Enable HTTPS
Protect admin endpoints
Validate all incoming requests
Store secrets in environment variables
Configure proper CORS policies

License

This project is intended for educational purposes and commercial lucky wheel campaigns. It can be extended and customized based on business requirements.