Codey Village is a gamified developer productivity platform that rewards real-world coding activity with in-game currency. Solve a LeetCode problem, push a GitHub commit, or submit a job application — and watch your village grow.

Built as a full-stack web app with a Phaser 3 multiplayer game at its core, a Python FastAPI backend, a Node.js OAuth middleware server, and a Manifest v3 Chrome extension that passively monitors your activity across LeetCode, GitHub, and Workday.

• Best Gamification Hack — GDG Hacks 3

• Devpost: https://devpost.com/software/cozyvillage
• Demo Video: https://www.youtube.com/watch?v=_GpzlR9-mik

• Overview
• Features
• Architecture
• Tech Stack
• Getting Started
  • Prerequisites
  • Backend (Python FastAPI)
  • OAuth/Webhook Server (Node.js)
  • Frontend (Next.js)
  • Chrome Extension
• Environment Variables
• Deployment
• API Overview
• Chrome Extension Details
• Multiplayer Architecture Notes
• License

Codey Village turns your daily developer workflow into a resource loop:

1. A Chrome extension silently watches LeetCode, GitHub, and Workday.
2. When it detects an accepted submission, a commit, or a job application, it fires a request to the FastAPI backend.
3. The backend awards coins to your account and stores your activity in MongoDB.
4. You spend those coins in the Next.js web app to build and decorate your island in a Phaser 3 top-down world.
5. You can join multiplayer rooms (up to 5 players) over WebSockets and roam each other's villages in real time.

┌─────────────────────────────────────────────────────────────┐
│                        Browser                              │
│                                                             │
│  ┌──────────────────────┐   ┌───────────────────────────┐  │
│  │   Next.js Frontend   │   │     Chrome Extension      │  │
│  │  (Phaser 3 Game UI)  │   │  (LeetCode / GitHub /     │  │
│  │  WebSocket client    │   │   Workday content scripts)│  │
│  └──────────┬───────────┘   └──────────┬────────────────┘  │
│             │                          │                    │
└─────────────┼──────────────────────────┼────────────────────┘
              │ HTTPS / WSS              │ HTTPS
              ▼                          ▼
┌─────────────────────────┐   ┌──────────────────────────┐
│  Python FastAPI Backend │   │  Node.js OAuth Server    │
│  ─────────────────────  │   │  ──────────────────────  │
│  REST API               │   │  GitHub OAuth flow       │
│  WebSocket (rooms)      │   │  GitHub webhook receiver │
│  Coin system            │   │  Activity tracker        │
│  Island / shop logic    │   └──────────────────────────┘
│  Firebase auth verify   │
│  ─────────────────────  │
│      MongoDB            │
└─────────────────────────┘

Data flow for a LeetCode coin award:

1. User solves a LeetCode problem in the browser.
2. The extension's leetcode.js content script detects the accepted submission.
3. Extension sends a POST to the FastAPI backend /coins/award.
4. Backend validates the Firebase auth token, increments user coins in MongoDB, and broadcasts to any active WebSocket room.
5. The frontend updates the coin counter in real time.

• Node.js 18+ and npm
• Python 3.11+
• MongoDB Atlas account (or local MongoDB instance)
• Firebase project with Authentication enabled
• Google Chrome (for the extension)
• A GitHub OAuth App (for the OAuth server)

cd backend
pip install -r requirements.txt

Create a .env file in backend/:

MONGO_URL=mongodb+srv://<user>:<pass>@<cluster>.mongodb.net/?appName=<app>
FIREBASE_API_KEY=<your-firebase-api-key>
WEBHOOK_URL=https://<your-backend-domain>

Start the development server:

uvicorn main:app --reload --port 8000

The API will be available at http://localhost:8000. Interactive docs are at http://localhost:8000/docs.

cd server
npm install

Create a .env file in server/:

GITHUB_CLIENT_ID=<your-github-oauth-app-client-id>
GITHUB_CLIENT_SECRET=<your-github-oauth-app-client-secret>
WEBHOOK_URL=https://<your-backend-domain>
PORT=3001

Start the server:

npm start

cd frontend
npm install

Create a .env.local file in frontend/:

NEXT_PUBLIC_IDENTITY_PLATFORM_API_KEY=<firebase-api-key>
NEXT_PUBLIC_IDENTITY_PLATFORM_AUTH_DOMAIN=<project>.firebaseapp.com
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000

Start the development server:

npm run dev

Open http://localhost:3000 in your browser.

Available scripts:

npm run dev      # Start development server (hot reload)
npm run build    # Build for production
npm run start    # Start production server
npm run lint     # Run ESLint

1. Open Chrome and navigate to chrome://extensions/.
2. Enable Developer mode (top-right toggle).
3. Click Load unpacked and select the extension/ directory.
4. The Codey Village extension icon will appear in your toolbar.
5. Sign in via the extension popup and connect your accounts.

The extension monitors:

• leetcode.com — problem submissions
• github.com — commit/push events
• Workday job application portals — application submissions

The Next.js app is deployed to Vercel. Connect the frontend/ directory as the Vercel project root and set the environment variables in the Vercel dashboard.

The FastAPI backend is deployed to Render. Connect your repository and set the environment variables in the Render dashboard. Use the following start command:

uvicorn main:app --host 0.0.0.0 --port 8000

The FastAPI backend exposes the following route groups:

Full interactive documentation is available at /docs (Swagger UI) and /redoc when the backend is running.

The extension uses Manifest v3 with a persistent service worker and the following content scripts:

An injected/interceptor.js script is injected into the page context (not the extension context) to intercept outgoing API requests from LeetCode and GitHub before they leave the browser, allowing the extension to detect events without polling.

The WebSocket room manager (backend/routes/ws_routes.py) holds all active room and player state in memory inside a RoomManager class. This means the backend must run as a single instance — splitting across multiple instances would cause players in the same room to connect to different instances with no shared state.

The natural path to horizontal scaling is to move room state to a Redis pub/sub layer, which would allow any number of backend instances to share room events. This is the primary scalability improvement for a production rollout.

GDG-HACKS3/
├── frontend/                   # Next.js web app
│   ├── app/                    # App Router pages (auth, lobby, game, room/[id])
│   ├── src/
│   │   ├── game/               # Phaser 3 game config, scenes, entities, map gen
│   │   ├── components/         # Shared React components
│   │   ├── hooks/              # Custom hooks (useCoins, useRoom, usePlayer)
│   │   ├── lib/                # Firebase, API client, Supabase utils
│   │   ├── store/              # Zustand game store
│   │   └── types/              # TypeScript type definitions
│   └── public/                 # Static assets and game sprites
│
├── backend/                    # Python FastAPI service
│   ├── main.py                 # App entrypoint, CORS, router registration
│   ├── models/                 # Pydantic data models
│   ├── controllers/            # Business logic
│   ├── routes/                 # API route handlers + WebSocket manager
│   ├── services/               # Firebase, GitHub, LeetCode integrations
│   └── database/               # MongoDB connection
│
├── server/                     # Node.js OAuth + webhook middleware
│   └── index.js                # Express app (GitHub OAuth, webhook receiver)
│
├── extension/                  # Chrome Extension (Manifest v3)
│   ├── manifest.json
│   ├── background/             # Service worker
│   ├── popup/                  # Extension popup UI
│   ├── content-scripts/        # Page-injected scripts (leetcode, github, workday)
│   ├── injected/               # In-page context scripts (API interceptor)
│   └── icons/                  # Extension icons (16, 48, 128px)
│
└── LICENSE                     # GNU GPL v3

This project is licensed under the GNU General Public License v3.0. See LICENSE for the full text.