From 3db63569e618b56096acd44e8fa3187a3891a0f1 Mon Sep 17 00:00:00 2001
From: Anahita-Mahmoudi <mahmoodianna23@gmail.com>
Date: Wed, 10 Jun 2026 15:57:34 +0330
Subject: [PATCH] docs: add project README with setup instructions

---
 backend/README.md | 329 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 329 insertions(+)
 create mode 100644 backend/README.md

diff --git a/backend/README.md b/backend/README.md
new file mode 100644
index 0000000..761289c
--- /dev/null
+++ b/backend/README.md
@@ -0,0 +1,329 @@
+# 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.