# 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 ```text 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 ```bash git clone cd spin-wheel ``` --- ## 2. Create a Virtual Environment ### Windows ```bash python -m venv venv venv\Scripts\activate ``` ### Linux / macOS ```bash python3 -m venv venv source venv/bin/activate ``` --- ## 3. Install Backend Dependencies ```bash cd backend pip install -r requirements.txt ``` --- ## 4. Configure Environment Variables Create a `.env` file inside the backend directory if required. Example: ```env DATABASE_URL=sqlite:///spinwheel.db ``` --- ## 5. Run Database Migrations ```bash alembic upgrade head ``` --- ## 6. Start Backend Server ```bash uvicorn main:app --reload ``` Backend API: ```text http://127.0.0.1:8000 ``` Swagger Documentation: ```text http://127.0.0.1:8000/docs ``` --- ## 7. Start Frontend Serve the frontend application on port 3000. Example: ```bash python -m http.server 3000 ``` Frontend URL: ```text http://localhost:3000/index.html http://localhost:3000/admin.html ``` --- # API Endpoints ## User APIs ### Get Rewards ```http GET /user/items ``` ### Spin the Wheel ```http POST /user/spin ``` Example Response: ```json { "id": 1, "reward_type": "DISCOUNT_CODE", "title": "20% Discount", "description": "Get 20% off on your next purchase.", "probability": 15 } ``` --- ## Admin APIs ### Get Rewards ```http GET /admin/items ``` ### Create Reward ```http POST /admin/items ``` ### Update Reward ```http PUT /admin/items/{id} ``` ### Delete Reward ```http 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.