marvijo-code / code-racer-cc

A competitive coding quiz game with real-time racing mechanics. Built with React frontend and ASP.NET Core backend.

🏎️ Code Racer

A Vite + React 2D racing game that teaches Software Engineering skills from beginner to Principal level. Race cars while answering programming questions at checkpoints, with semantic similarity detection to prevent duplicate questions.

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• .NET 9 SDK
• Node.js 18+

Option 1: Simple Startup (Recommended)

# Start backend and database
./start-simple.sh

# In a new terminal, start frontend
cd frontend
npm run dev

Option 2: Manual Setup

# 1. Start PostgreSQL
docker-compose up -d postgres

# 2. Setup database
cd backend
dotnet ef database update
cd ..

# 3. Start backend
cd backend
dotnet run --launch-profile http
# Backend will be available at http://localhost:5000

# 4. In a new terminal, start frontend
cd frontend
npm run dev
# Frontend will be available at http://localhost:5173

🎮 How to Play

1. Start a Race: Click "🏁 Start Race"
2. Drive: Use arrow keys to control your car
   • ↑ Arrow: Accelerate
   • ↓ Arrow: Brake/Reverse
   • ← → Arrows: Steer
3. Answer Questions: Hit orange checkpoints to trigger programming quizzes
4. Lives System: You have 3 lives - lose one for each wrong answer
5. Spectator Mode: After 3 wrong answers, watch the AI complete the race
6. Leaderboard: Complete races are ranked by time and score

🏗️ Architecture

Frontend (React + TypeScript + Vite)

• Game Engine: PIXI.js 60 FPS 2D rendering
• State Management: Zustand with async API integration
• Styling: Tailwind CSS
• Real-time Communication: API calls with planned SignalR integration

Backend (.NET 9 + PostgreSQL)

• APIs: Minimal APIs with Entity Framework Core 9
• Database: PostgreSQL with EF Core migrations
• Semantic Similarity: Cosine similarity for question uniqueness
• Real-time: SignalR hubs for multiplayer features

Key Features

• ✅ 60 FPS racing with physics
• ✅ 10-second quiz countdown
• ✅ Spectator mode after 3 wrong answers
• ✅ Score submission and leaderboard
• ✅ Semantic question similarity detection
• ✅ Real-time multiplayer foundation

🔗 API Endpoints

• GET /health - Health check
• POST /v1/sessions - Create new race session
• PATCH /v1/sessions/{id}/answer - Submit quiz answer
• GET /v1/questions/random - Get random question
• GET /v1/leaderboards - Get top 10 leaderboard
• POST /v1/admin/seed - Seed sample questions

🧪 Testing

# Test API health
curl http://localhost:5000/health

# Get a random question
curl http://localhost:5000/v1/questions/random

# View leaderboard
curl http://localhost:5000/v1/leaderboards

🐳 Docker Services

The docker-compose.yml includes:

• PostgreSQL 16: Primary database
• Milvus: Vector database for semantic similarity (planned)

🔧 Development

Backend

cd backend
dotnet build
dotnet test
dotnet run

Frontend

cd frontend
npm install
npm run dev
npm run build

🛠️ Troubleshooting

Frontend Rollup Error

If you see "Cannot find module @rollup/rollup-*", run:

cd frontend
rm -rf node_modules package-lock.json
npm install

Backend Port Issues

Backend should run on port 5000. Check backend/Properties/launchSettings.json if needed.

Database Connection

Ensure PostgreSQL is running:

docker-compose up -d postgres

🎯 What's Next

This is the Minimal Playable Game (MPG) implementation. Future enhancements include:

• User authentication and profiles
• Advanced multiplayer with live race spectating
• Full Milvus vector database integration
• Cloud deployment (Azure AKS)
• Mobile app (React Native)
• AI-generated questions

📝 License

MIT License - see LICENSE file for details.