fast_api_livetse/backend/README.md

# 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 <repository-url>
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.