๐ Live Demo โข ๐ Documentation โข โจ Features โข ๐ Getting Started โข ๐ค Contributing
Live Application URL: https://novaplay-demo.vercel.app (Replace with your live production URL)
API Status: Operational | Target Deployment: Vercel (Frontend) / Node.js + MongoDB Atlas (Backend)
+-------------------------------------------------------------------------------+
| |
| [ ๐ธ INSERT HERO / DASHBOARD SCREENSHOT ] |
| |
| Recommended: 1280x720 screenshot of the NOVAPLAY catalog and active game |
| assets/screenshots/novaplay-hero-banner.png |
| |
+-------------------------------------------------------------------------------+
- Executive Overview
- System Architecture
- Tech Stack
- Key Features
- Game Catalog Breakdown
- Directory Structure
- Getting Started & Local Installation
- Environment Configuration (.env.example)
- Screenshots & UI Showcase
- CI/CD Pipeline
- Contributing
- License & Author
NOVAPLAY is a modern, responsive full-stack gaming ecosystem engineered to bring classic arcade, puzzle, strategy, board, card, and sports titles into a single, cohesive web platform. Designed with performance, accessibility, and clean architecture as first-class citizens, NOVAPLAY pairs a responsive React/Next.js frontend with low-latency client rendering, customizable audio synthesis, and persistent cloud session tracking via Node.js and MongoDB.
- Modular Component Design: Decoupled game engine logic with 70+ playable titles isolated into self-contained React functional components.
- Custom React Hooks: Business logic, game state loops, audio synthesis, and window lifecycle events are cleanly separated into reusable, testable hooks.
- Full-Stack Data Persistence: User progression, recently played history, game analytics, and theme state are managed through a dual-tier strategy (optimistic client persistence + MongoDB cloud synchronization).
- Zero-Latency Audio Engine: Built-in Web Audio API synthesizer generates retro sound effects and ambient tracks dynamically without blocking network assets.
- PWA & Offline Capability: Service worker caching allows offline gameplay across desktop, tablet, and mobile form factors.
graph TD
Client[Client Browser / PWA] -->|Interactions & State| ReactUI[React 19 / Next.js Client App]
ReactUI -->|Game Logic & Loops| CustomHooks[Custom React Hooks]
ReactUI -->|Low-Latency SFX| AudioEngine[Web Audio API Engine]
ReactUI -->|HTTP / JSON| APIRoutes[Next.js / Node.js API Routes]
APIRoutes -->|Mongoose ODM| MongoEngine[(MongoDB Database)]
Client -->|Local Fallback| LocalStorage[(Client LocalStorage)]
subgraph Frontend Layer
ReactUI
CustomHooks
AudioEngine
end
subgraph Backend & Persistence Layer
APIRoutes
MongoEngine
LocalStorage
end
| Domain | Technology | Purpose |
|---|---|---|
| Frontend Framework | React 19 & Next.js | Server-side rendering, component-driven UI, fast client navigation |
| Language | TypeScript 5.9 | Strict type safety, clean interface contracts, fewer runtime bugs |
| Styling & Design | Tailwind CSS 4.0 | Utility-first CSS, dark/light theme switching, responsive layouts |
| Backend & APIs | Node.js & Next.js Route Handlers | RESTful endpoints for game scores, session tracking, and user data |
| Database | MongoDB & Mongoose | Flexible document store for player profiles, game states, and leaderboards |
| Audio Processing | HTML5 Web Audio API | Real-time procedural tone generation and dynamic sound effects |
| Build & Bundling | Vite / Next.js Bundler | Fast HMR (Hot Module Replacement) and optimized production bundles |
| CI / CD | GitHub Actions | Automated linting, typechecking, and build validation on push/PR |
- ๐ฎ 70+ Fully Playable Titles: Classic arcade hits, spatial puzzles, strategic board games, word challenges, and card tournaments built into one application.
- ๐ Dynamic Theming Engine: Smooth toggle between Dark Mode and Light Mode with zero flicker, synced with system preferences and local storage.
- ๐ Player Progression & Game History: Tracks recently played games, high scores, time spent, and game completion statuses.
- ๐ Procedural Sound Effects & Audio Controls: Toggleable volume, master mute, and synthesizers tailored for 8-bit retro audio.
- ๐ Instant Search & Multi-Tag Filtering: Debounced client search to query titles, descriptions, and category metadata in real-time.
- ๐ฑ Responsive & Touch-Optimized: Fluid layouts supporting full keyboard controls (WASD/Arrows) and touch screens for mobile gaming.
- ๐ก Defensive Error Handling: React Error Boundaries and graceful API fallbacks ensure single-game failures never crash the platform.
| Category | Representative Titles | Key Mechanics |
|---|---|---|
| ๐น Arcade | Asteroids, Pacman, Galaga, Space Invaders, Frogger, Dig Dug, Flappy Bird | 2D Canvas rendering, collision detection, game loops |
| ๐งฉ Puzzle | Sudoku, Minesweeper, Sokoban, Sliding Puzzle, Lights Out, Nonogram | Grid backtracking, constraint satisfaction, recursive flood-fill |
| โ Board & Strategy | Chess, Checkers, Reversi, Connect Four, Battleship, Dots & Boxes | Turn-based state machines, minimax AI, win-condition matrix checks |
| ๐ Card Games | Blackjack, Spider Solitaire, War | Deck shuffling (Fisher-Yates), card animations, dealer rules |
| โฝ Sports & Physics | Air Hockey, Mini Golf, Bowling, Pool Table, Darts, Penalty Kicks | 2D vector physics, velocity dampening, angle reflections |
| ๐ Word Games | Wordle, Word Search | Dictionary validation, string indexing, letter frequency scoring |
NOVAPLAY/
โโโ .github/
โ โโโ workflows/
โ โโโ ci.yml # GitHub Actions automated build pipeline
โโโ public/
โ โโโ logo.png # Platform branding
โ โโโ manifest.json # PWA manifest
โ โโโ sw.js # Service worker offline caching
โโโ src/
โ โโโ components/ # Shared UI components (Modals, Nav, Cards)
โ โโโ hooks/ # Extracted business logic & custom hooks
โ โโโ games/ # 70+ modular game implementations
โ โ โโโ AirHockey.tsx
โ โ โโโ Asteroids.tsx
โ โ โโโ ChessSimple.tsx
โ โ โโโ Sudoku.tsx
โ โ โโโ ...
โ โโโ lib/ # Database connections & server utilities
โ โ โโโ dbConnect.ts # Cached MongoDB connection handler
โ โโโ utils/ # Helper functions, class merging (cn.ts)
โ โโโ App.tsx # Main client shell & router
โ โโโ gameCatalog.ts # Game metadata registry
โ โโโ gameGuides.ts # Built-in tutorials & game instructions
โ โโโ gameRegistry.ts # Lazy-loaded component map
โ โโโ toyAudio.ts # Web Audio API engine
โ โโโ main.tsx # Client entry point
โโโ .env.example # Sanitized environment variable template
โโโ package.json # Project dependencies & scripts
โโโ tsconfig.json # TypeScript compiler config
โโโ vite.config.ts # Vite build configuration
Follow these steps to set up and run NOVAPLAY locally on your machine.
- Node.js:
v18.xor higher (Download Node.js) - npm (comes with Node) or yarn / pnpm
- MongoDB: Local MongoDB instance (
mongod) or a free MongoDB Atlas Cluster - Git: Installed and configured
git clone https://github.com/your-username/novaplay.git
cd novaplaynpm installCreate your local .env file by copying the provided example:
cp .env.example .envOpen .env in your editor and configure your variables:
NODE_ENV=development
PORT=3000
MONGODB_URI=mongodb://localhost:27017/novaplay
NEXTAUTH_SECRET=your_secret_key_herenpm run devOpen your browser and navigate to:
http://localhost:5173 # (or http://localhost:3000 depending on runner)
To test the production build locally:
# Compile and bundle
npm run build
# Preview production build
npm run previewAll sensitive variables and runtime options are abstracted into .env. A complete template is provided in .env.example:
| Variable | Required | Description | Example / Default |
|---|---|---|---|
NODE_ENV |
Yes | Application environment mode | development / production |
PORT |
No | Local server port | 3000 |
MONGODB_URI |
Yes | MongoDB connection string | mongodb://localhost:27017/novaplay |
MONGODB_DB_NAME |
No | Database name | novaplay |
JWT_SECRET |
Yes | Secret used for signing authentication tokens | openssl rand -base64 32 |
NEXTAUTH_SECRET |
Optional | NextAuth session encryption secret | your_nextauth_secret |
NEXT_PUBLIC_APP_URL |
Yes | Canonical base URL of the client | http://localhost:3000 |
NEXT_PUBLIC_API_BASE_URL |
Yes | Base endpoint for API requests | http://localhost:3000/api |
(Add your high-resolution screenshots to /assets/screenshots/ and update the links below)
| Catalog & Category Filter | In-Game View (Arcade / Puzzle) |
|---|---|
![]() |
![]() |
| Light & Dark Theme Toggle | Responsive Mobile View |
|---|---|
![]() |
![]() |
This repository includes a continuous integration workflow powered by GitHub Actions located at .github/workflows/ci.yml.
- Triggers: Push to
mainbranch, and all Pull Requests targetingmain. - Validation Steps:
- Automated checkout with clean Node.js runtime setup.
- Dependency caching via
actions/setup-node. - Strict package installation (
npm ci). - Typecheck & production build compilation (
npm run build).
Contributions make the open-source community an inspiring place to learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'feat: Add AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.
Author: Umesh Kumar Shah
- GitHub: @your-github-username
- LinkedIn: linkedin.com/in/your-profile
- Portfolio: your-portfolio-link.com



