Spaces:
Sleeping
Download README.md from jinksQspider/SSC: direct link, hf CLI and curl.
- Browser
- Download file 8.98 kB
-
https://huggingface.co/spaces/jinksQspider/SSC/resolve/main/README.md
- Command line
-
hf download hf://spaces/jinksQspider/SSC/README.md
-
curl -L -o README.md https://huggingface.co/spaces/jinksQspider/SSC/resolve/main/README.md
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
- Navigate to backend directory
cd backend
- Create virtual environment
python -m venv venv
source venv/Scripts/activate # Windows
# or
source venv/bin/activate # Unix/Mac
- Install dependencies
pip install -r requirements.txt
- Create .env file
cp .env.example .env
- Initialize database
python -c "from app.database import init_db; init_db()"
- 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
- Navigate to frontend directory
cd frontend
- Install dependencies
npm install
- Run development server
npm run dev
Frontend will be available at http://localhost:3000
π API Endpoints
Authentication
POST /auth/register- Register new playerPOST /auth/login- Login player
Players
GET /players/me- Get current player profilePUT /players/me- Update current player profileGET /players/{player_id}- Get player profile by IDGET /players- Get all playersGET /players/leaderboard/top-performers- Top 10 scorersGET /players/leaderboard/by-wickets- Top wicket-takers
Premium
POST /premium/upgrade- Upgrade to premiumGET /premium/status- Check premium statusPOST /premium/cancel- Cancel premiumGET /premium/payments- Payment history
Performance
POST /performance- Log performanceGET /performance/my-logs- Get own performance logsGET /performance/player/{player_id}- Get player's logsGET /performance/stats/{player_id}- Get player stats
Dashboard
GET /dashboard/overview- System overviewGET /dashboard/featured-players- Featured premium playersGET /dashboard/recent-players- Recently joined playersGET /dashboard/top-stats- Top performers
Admin
GET /admin/users- List all usersPUT /admin/users/{user_id}/premium- Toggle premiumDELETE /admin/users/{user_id}- Deactivate userGET /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)
- Copy backend env template:
cp backend/.env.example backend/.env
- Update secrets in
backend/.env:
SECRET_KEYADMIN_PASSWORDCORS_ORIGINS(set your real frontend domain)
- Build and run production stack:
docker compose -f docker-compose.prod.yml up -d --build
- 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)
Create Hugging Face account and new Space (Docker)
Copy/create required files in Space repo:
Dockerfile.huggingface docker-entrypoint.sh nginx-huggingface.conf backend/ frontend/Rename or use Dockerfile as:
cp Dockerfile.huggingface Dockerfile chmod +x docker-entrypoint.shSet secrets in Space settings:
SECRET_KEY: Generate strong random stringADMIN_PASSWORD: Your secure admin password
Push to Hugging Face repo - Space auto-builds and deploys
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