GameHub: Cosmic Edition

Experience the next generation of browser gaming. High-performance, low-latency, and stunning cosmic aesthetics.

About • Technical Docs • Quick Start • API • Contribute • Request Feature

---

The Cosmic Neon Library Interface

---

Protocol Guidelines (ECWoC26)

Important

• Star the Repo: Your contribution only counts if you've starred the repository. ⭐
• Documentation: Proper docs are required for every new feature. Share them via mail.
• Meaningful Issues: Only high-impact issues will be considered.
• Leaderboard Priority: Priority is given to contributors with lower ranks.

---

Table of Contents

• 💡 About GameHub
• ✨ Features
• 🛠️ Tech Stack
• 📁 Project Structure
• 🚀 Quick Start
• 🔑 Environment Variables
• 📡 API Reference
• 🎮 Adding New Games
• 🌟 Contributing
• ✨ Contributors
• 📄 License

---

💡 About GameHub

GameHub is an elite, open-source collection of classic and modern browser games. Re-imagined with a Cosmic Blue Neon aesthetic, it combines the nostalgia of retro gaming with the performance of industry-standard web tech.

Originally a Vanilla JS project, GameHub has been upgraded to a React + Django REST Framework hybrid architecture supporting massive scalability, premium animations, a global leaderboard system, full JWT authentication, Google OAuth 2.0, PWA installability, and a password reset flow.

---

✨ Features

Feature	Description
🚀 Modern Engine	Built with React 19 + Vite 7 for sub-millisecond responsiveness.
🎨 Cosmic UI	High-end Glassmorphism and Neon design system with Framer Motion animations.
🕹️ 50+ Titles	Instant play library including retro classics and modern games.
🏆 Leaderboards	Global competition powered by a Django REST backend.
� Full Auth	JWT login/register + Google OAuth 2.0 (id_token flow).
🔑 Password Reset	Secure email-based forgot/reset password flow.
📱 PWA Ready	Installable as a native app on any device. Dismiss-once prompt.
🛠️ Modular Code	Clean architecture designed for easy open-source contribution.

---

🛠️ Tech Stack

Tier	Technology	Notes
Frontend	React 19, Framer Motion	SPA with file-based routing
Styling	Tailwind CSS 4, Lucide Icons	Cosmic Neon design tokens
Backend	Django 4+ REST Framework	JWT via djangorestframework-simplejwt
Auth	JWT + Google OAuth 2.0	google-auth library for id_token verification
State	Zustand	Persistent auth store
Build	Vite 7 (Ultra-fast HMR)	PWA via vite-plugin-pwa
API Docs	drf-spectacular	OpenAPI 3.0 + Swagger UI at /api/schema/swagger-ui/

---

📁 Project Structure

GameHub/
├── frontend/                   # React Application (Vite)
│   ├── src/
│   │   ├── api/                # Axios instance + JWT interceptor
│   │   ├── components/
│   │   │   ├── GoogleAuth/     # GoogleAuthButton (id_token flow)
│   │   │   ├── Navbar/
│   │   │   ├── Footer/
│   │   │   ├── SEO/
│   │   │   └── PWAInstallPrompt.jsx  # Smart one-time install banner
│   │   ├── pages/              # Login, Register, Profile, Games…
│   │   ├── data/               # games.js registry
│   │   └── store/              # Zustand auth store
│   ├── public/                 # Static assets & game files
│   ├── .env                    # VITE_GOOGLE_CLIENT_ID
│   └── vite.config.js          # PWA + proxy + COOP headers
│
├── backend/                    # Django REST API
│   ├── accounts/
│   │   ├── views.py            # All API endpoints incl. Google OAuth
│   │   ├── models.py           # Profile, GameScore, UserMessage
│   │   └── urls.py             # API route definitions
│   ├── gamehub_project/
│   │   └── settings.py         # CORS, JWT, Google Client ID, COOP
│   ├── .env                    # GOOGLE_CLIENT_ID + SECRET_KEY
│   └── requirements.txt
│
├── DOCS.md                     # Technical Deep-Dive
└── README.md                   # This file

---

🚀 Quick Start

1️⃣ Clone the Repo

git clone https://github.com/kaifansariw/GameHub.git
cd GameHub

2️⃣ Initialize Frontend

cd frontend
npm install
# Create your .env (copy values from .env.example if present)
npm run dev
# Runs on http://localhost:5173

3️⃣ Initialize Backend

cd backend
python -m venv venv
# Windows:
.\venv\Scripts\activate
# Mac/Linux:
source venv/bin/activate

pip install -r requirements.txt
python manage.py migrate
python manage.py runserver
# Runs on http://localhost:8000

---

🔑 Environment Variables

frontend/.env

VITE_GOOGLE_CLIENT_ID=your_google_oauth_client_id.apps.googleusercontent.com

backend/.env

SECRET_KEY=your_django_secret_key
DEBUG=True
GOOGLE_CLIENT_ID=your_google_oauth_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_google_oauth_client_secret

Tip

Get your Google OAuth credentials from console.cloud.google.com/apis/credentials. Add http://localhost:5173 and http://localhost:8000 as an Authorized JavaScript Origin.

---

📡 API Reference

Full interactive docs at http://localhost:8000/api/schema/swagger-ui/

Method	Endpoint	Auth	Description
POST	/api/auth/login/	❌	Login with username/email + password
POST	/api/auth/register/	❌	Create a new account
POST	/api/auth/google/	❌	Login/register via Google id_token
POST	/api/auth/token/refresh/	❌	Refresh JWT access token
POST	/api/auth/password-reset/	❌	Send reset email
POST	/api/auth/password-reset-confirm/	❌	Confirm password reset
GET	/api/profile/	✅	Get authenticated user profile
GET	/api/leaderboard/	❌	Global ranked leaderboard
POST	/api/add-visit/	✅	Record a game page visit
POST	/api/add-play/	✅	Record a game play
POST	/api/save-score/	✅	Save/update a game high score
POST	/api/send-feedback/	❌	Submit feedback

---

🎮 Adding New Games

Registering a new title in the Cosmic Library:

1. Upload Assets: Place files in frontend/public/games/<game-id>/
2. Register Metadata: Edit frontend/src/data/games.js:

{
    id: "quantum-racer",
    title: "Quantum Racer",
    description: "Multi-dimensional racing experience.",
    image: "/assets/thumbs/quantum.png",
    file: "/games/quantum/index.html",
    category: "racing"
}

---

🌟 Contributing

We ❤️ our contributors! Whether it's a bug fix or UI polish:

1. Fork → Branch (git checkout -b feat/CoolFeature) → Commit → Push → PR.

Note

Every new feature should include a brief description in DOCS.md and follow the existing code style.

---

✨ Contributors

The heroes behind the Cosmic Engine:

---

📄 License

This project is licensed under the MIT License.

---

Maintained by Kaif Ansari & the Open Source Community

---

Back to Top ↑