4.8 KiB
Spin Wheel System
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.