SSC / README.md
Hkoradiya123
feat: Update README with Docker setup and deployment options
3ba45b3
|
Raw History Blame Contribute Delete
8.98 kB
metadata
title: SSC
emoji: πŸ“‰
colorFrom: purple
colorTo: yellow
sdk: docker
pinned: false
license: mit
short_description: SculptSoft Cricketers

SSC - Sculpt Soft Cricketers

A complete web-based player management and performance tracking system for cricket players. Built with FastAPI backend and React frontend, featuring a freemium subscription model.

🎯 Features

Core Features

  • Player Registration & Authentication - Secure JWT-based authentication
  • Player Profiles - Manage player information and statistics
  • Performance Tracking - Log matches, runs, wickets, and achievements
  • Premium Subscription - β‚Ή1000/month membership with featured status
  • Leaderboards - Top scorers and wicket-takers rankings
  • Dashboard - Centralized overview of all players and stats
  • Admin Panel - System management and user administration

Additional Features

  • Real-time Notifications - Premium expiry alerts and achievements
  • Performance Logs - Detailed match-by-match performance history
  • Rate Limiting - API protection against abuse
  • Comprehensive Logging - System activity tracking
  • CORS Support - Cross-origin resource sharing
  • API Documentation - Interactive Swagger/OpenAPI docs

πŸ“‹ Tech Stack

Backend

  • Framework: FastAPI
  • Database: SQLite
  • ORM: SQLAlchemy
  • Authentication: JWT with PassLib
  • API Rate Limiting: SlowAPI

Frontend

  • Framework: React 18
  • Build Tool: Vite
  • Routing: React Router v6
  • API Client: Axios
  • Charts: Chart.js with React wrapper

πŸš€ Getting Started

Prerequisites

  • Python 3.8+
  • Node.js 16+
  • pip (Python package manager)
  • npm (Node package manager)

Backend Setup

  1. Navigate to backend directory
cd backend
  1. Create virtual environment
python -m venv venv
source venv/Scripts/activate  # Windows
# or
source venv/bin/activate  # Unix/Mac
  1. Install dependencies
pip install -r requirements.txt
  1. Create .env file
cp .env.example .env
  1. Initialize database
python -c "from app.database import init_db; init_db()"
  1. Run development server
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Backend API will be available at http://localhost:8000 API Docs: http://localhost:8000/docs

Frontend Setup

  1. Navigate to frontend directory
cd frontend
  1. Install dependencies
npm install
  1. Run development server
npm run dev

Frontend will be available at http://localhost:3000

πŸ“š API Endpoints

Authentication

  • POST /auth/register - Register new player
  • POST /auth/login - Login player

Players

  • GET /players/me - Get current player profile
  • PUT /players/me - Update current player profile
  • GET /players/{player_id} - Get player profile by ID
  • GET /players - Get all players
  • GET /players/leaderboard/top-performers - Top 10 scorers
  • GET /players/leaderboard/by-wickets - Top wicket-takers

Premium

  • POST /premium/upgrade - Upgrade to premium
  • GET /premium/status - Check premium status
  • POST /premium/cancel - Cancel premium
  • GET /premium/payments - Payment history

Performance

  • POST /performance - Log performance
  • GET /performance/my-logs - Get own performance logs
  • GET /performance/player/{player_id} - Get player's logs
  • GET /performance/stats/{player_id} - Get player stats

Dashboard

  • GET /dashboard/overview - System overview
  • GET /dashboard/featured-players - Featured premium players
  • GET /dashboard/recent-players - Recently joined players
  • GET /dashboard/top-stats - Top performers

Admin

  • GET /admin/users - List all users
  • PUT /admin/users/{user_id}/premium - Toggle premium
  • DELETE /admin/users/{user_id} - Deactivate user
  • GET /admin/stats - System statistics

πŸ”‘ Default Admin Credentials

Email: admin@ssc.com
Password: admin123

πŸ“Š Database Schema

Users Table

  • id, name, email, password
  • jersey_number, role, bio
  • runs, matches, wickets
  • is_premium, premium_expiry
  • is_active, created_at, updated_at

Payments Table

  • id, user_id, amount
  • payment_method, transaction_id
  • status, plan_duration_days

Performance Logs Table

  • id, user_id, match_date
  • runs_scored, wickets_taken
  • match_type, opponent
  • performance_rating, notes

Notifications Table

  • id, user_id, title, message
  • notification_type, is_read, created_at

🎨 Premium Features

Players can upgrade to Premium (β‚Ή1000/month) to:

  • ✨ Get featured on the dashboard
  • πŸ“Š Access advanced analytics
  • πŸ”” Get priority notifications
  • πŸ† Appear in premium players list

Premium membership auto-downgrades after 30 days.

πŸ“ Additional Features Implemented

1. Performance Analytics

  • Track century and half-century achievements
  • Calculate batting averages
  • Highest score tracking
  • Match-by-match performance logs

2. Ranking System

  • Player rankings by total runs
  • Top wicket-taker leaderboard
  • Premium member spotlight

3. Activity Logging

  • Comprehensive API request logging
  • User action tracking
  • Error tracking and reporting

4. Rate Limiting

  • API rate limiting to prevent abuse
  • Per-endpoint throttling
  • Graceful error responses

5. Notification System

  • Premium expiry notifications
  • Achievement notifications
  • Customizable notification types

6. Admin Dashboard

  • View all users
  • Toggle user premium status
  • Deactivate users
  • View system statistics

🐳 Docker Setup

Development (hot reload)

docker-compose up -d --build

This starts backend on http://localhost:8000 and frontend on http://localhost:3000.

Production-ready (Nginx + Gunicorn)

  1. Copy backend env template:
cp backend/.env.example backend/.env
  1. Update secrets in backend/.env:
  • SECRET_KEY
  • ADMIN_PASSWORD
  • CORS_ORIGINS (set your real frontend domain)
  1. Build and run production stack:
docker compose -f docker-compose.prod.yml up -d --build
  1. Open app at http://localhost.

Production stack includes:

  • Frontend served by Nginx on port 80
  • Reverse proxy /api -> backend service
  • Backend served by Gunicorn + Uvicorn workers
  • Persistent SQLite volume ssc-db-data

πŸ“– Environment Variables

Backend (.env)

Use backend/.env.example as base.

Important variables:

DATABASE_URL=sqlite:////app/data/ssc.db
SECRET_KEY=CHANGE_THIS
DEBUG=False
CORS_ORIGINS=https://your-frontend-domain.com

Frontend (.env)

For development:

VITE_API_URL=http://localhost:8000

For production Docker build, frontend uses /api via Nginx proxy.

πŸ§ͺ Testing

Test Authentication

curl -X POST "http://localhost:8000/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com","password":"pass123"}'

Test API with Token

curl -X GET "http://localhost:8000/players/me" \
  -H "Authorization: Bearer {token}"

πŸš€ Deployment

Option 1: Hugging Face Spaces (Easiest - Both Backend + Frontend)

  1. Create Hugging Face account and new Space (Docker)

  2. Copy/create required files in Space repo:

    Dockerfile.huggingface
    docker-entrypoint.sh
    nginx-huggingface.conf
    backend/
    frontend/
    
  3. Rename or use Dockerfile as:

    cp Dockerfile.huggingface Dockerfile
    chmod +x docker-entrypoint.sh
    
  4. Set secrets in Space settings:

    • SECRET_KEY: Generate strong random string
    • ADMIN_PASSWORD: Your secure admin password
  5. Push to Hugging Face repo - Space auto-builds and deploys

  6. Access your app:

    https://huggingface.co/spaces/{your-username}/{your-space-name}
    

Your app runs on port 7860 with:

  • Frontend: Served by Nginx
  • Backend: Internal port 8000
  • API proxy: /api β†’ backend
  • Docs still available at /docs

Option 2: Docker Compose (Local or VPS)

docker compose -f docker-compose.prod.yml up -d --build

Access at http://localhost

Option 3: Separate Deployment

Backend:

  • Heroku
  • AWS EC2
  • Google Cloud Run
  • DigitalOcean
  • Railway.app

Frontend:

  • Vercel (recommended)
  • Netlify
  • AWS S3 + CloudFront
  • GitHub Pages

πŸ”’ Security Features

  • JWT-based authentication
  • Password hashing with bcrypt
  • CORS protection
  • Rate limiting
  • SQL injection prevention (via SQLAlchemy ORM)
  • Admin role verification

πŸ“ž Support & Contribution

For issues and feature requests, please create an issue in the repository.

πŸ“„ License

This project is open source and available under the MIT License.

πŸŽ“ Learning Resources

This project demonstrates:

  • Modern API design with FastAPI
  • Database design with SQLAlchemy
  • JWT authentication
  • Frontend development with React
  • Responsive UI design
  • Subscription-based SaaS architecture