Legacy Code: The Retail Singularity.

A browser-based MMO where your convenience store is a front for reality-stabilizing rituals

🎮 Status: MVP Complete (56/56 tasks, 5 sprints) | 🚀 Deployment: Docker-ready | 📊 Test Coverage: 60%+ (92 tests) | 🔒 Security: Audit complete, roadmap available

---

🎯 Quick Start

Prerequisites

• Docker & Docker Compose
• (Or: Node 20+, PostgreSQL 16, Redis 7)

Run with Docker (Recommended)

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Access Points:

• 🌐 Game: http://localhost:3000
• 🔧 API: http://localhost:3001
• 👤 Admin: http://localhost:3000/admin

Run Locally (Development)

# Install dependencies
npm install

# Set up database
cd apps/server
npm run prisma:migrate
npm run prisma:generate

# Start server
npm run dev

# Start web (in another terminal)
cd apps/web
npm run dev

---

🎮 How to Play

1. Create Account at http://localhost:3000/login
2. Move around with WASD or Arrow keys
3. Click NPCs (customers) to start serving them
4. Scan items in the register UI
5. Check IDs for restricted items (21+ only)
6. Earn currency & XP by completing transactions
7. Chat with other players (Enter to focus)
8. Press F1 for full keybinds list

Game Mechanics

NPC Types:

• 🟦 Normal - Patient, average pay
• 🟧 Impatient - Low patience, bonus XP if served quickly
• 🟪 Underage - Tries to buy restricted items, deny for XP
• 🟥 Karen - Very impatient, complains, high pay
• 🔷 Glitch - Weird requests, pays 2x

Progression:

• Level up by earning XP
• Unlock abilities and skills
• Earn currency to buy items
• Join franchises (guilds)
• Capture territory nodes

---

🏗️ Architecture

Tech Stack

Frontend:

• Next.js 14 (App Router)
• Phaser 3 (2D game engine)
• React + TailwindCSS
• Zustand (state)
• Socket.io Client

Backend:

• Node.js 20 + TypeScript
• Express (REST API)
• Socket.io (WebSockets)
• PostgreSQL 16 (Prisma ORM)
• Redis 7 (cache)

Infrastructure:

• Docker Compose
• Multi-stage builds
• Hot-reload in dev
• Health checks

Project Structure

legacy-code-mmo/
├── apps/
│   ├── web/          # Next.js frontend
│   ├── server/       # Node.js backend
│   └── admin/        # Admin portal (in progress)
├── packages/
│   ├── types/        # Shared TypeScript types
│   └── constants/    # Game balance & config
├── docs/             # Design documents
└── docker-compose.yml

Game Loop

• 20 TPS server tick rate (50ms intervals)
• Server-authoritative - prevents cheating
• Client-side prediction - smooth movement
• Event-driven systems - NPCs, Combat, Skills

---

📋 Features

✅ Completed (Playable Now!)

Phase A: Foundation

• ✅ Player movement & multiplayer
• ✅ WebSocket real-time sync
• ✅ Auth & JWT tokens
• ✅ Docker deployment

Phase B: Core Loop

• ✅ NPC spawning (5 types)
• ✅ Scanning/register UI
• ✅ Currency & XP system
• ✅ Player HUD (level, XP, currency)
• ✅ Text chat

Server-Side Complete (UI in progress):

• ✅ Combat system (4 roles, 12+ abilities)
• ✅ Skill system (10 skills)
• ✅ Inventory & equipment
• ✅ Crafting (Mixology + Synthesis)
• ✅ Player market
• ✅ Franchise/guild system
• ✅ Housing system
• ✅ Territory control
• ✅ Daily quests

🚧 In Progress

• 🔨 Combat UI (abilities, cooldowns)
• 🔨 Inventory UI
• 🔨 Crafting UI
• 🔨 Skills progression UI
• 🔨 Market UI
• 🔨 Housing decoration UI
• 🔨 Franchise management UI
• 🔨 Daily quests tracker

📝 Planned

• 📋 Tutorial system
• 📋 First dungeon "The Back Room"
• 📋 Additional dungeons & raids
• 📋 Load testing & optimization
• 📋 Comprehensive test suite

---

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run specific test suite
npm test -- NPCSystem

# Coverage report
npm run test:coverage

Current Coverage: 60%+ (92 tests passing)

---

🔧 Development

Available Scripts

# Root
npm install              # Install all dependencies
npm run dev              # Start all dev servers
npm run build            # Build all apps
npm test                 # Run all tests

# Server (apps/server/)
npm run dev              # Start dev server with hot-reload
npm run build            # Build production
npm run prisma:migrate   # Run migrations
npm run prisma:studio    # Open Prisma Studio

# Web (apps/web/)
npm run dev              # Start Next.js dev server
npm run build            # Build production
npm run lint             # Run ESLint

Environment Variables

Create .env files in each app:

apps/server/.env:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/legacy_code_mmo
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key-change-in-production
PORT=3001
NODE_ENV=development
CLIENT_URL=http://localhost:3000

apps/web/.env.local:

NEXT_PUBLIC_SERVER_URL=http://localhost:3001
NEXT_PUBLIC_ADMIN_PASSWORD=admin123
NEXT_TELEMETRY_DISABLED=1

---

📚 Documentation

Core Documentation:

• CLAUDE.md - Project status & quick start
• ARCHITECTURE.md - System design & technical overview
• CONVENTIONS.md - Coding standards

Pre-Launch Roadmaps:

• SECURITY_ROADMAP.md - 2 CRITICAL + 5 MEDIUM security issues & fixes
• TESTING_IMPROVEMENTS.md - P0 tests needed (20-25 hours)
• CODE_QUALITY_ROADMAP.md - Refactoring opportunities (12-16 hours)

Game Design & Features:

• GAME_STATUS.md - Feature completion status
• BACK_ROOM_DESIGN.md - First dungeon design
• PLAYTESTING_GUIDE.md - Testing procedures

Operations:

• DEPLOYMENT.md - Docker & production setup
• PERFORMANCE_TESTING.md - Load testing & optimization

---

🎨 Game Design

Genre: Incremental MMO + Corporate Horror Theme: Mundane retail → Eldritch cosmic horror Target: 2-100 concurrent players Sessions: 5-15 minute bursts (office-friendly)

Core Loop:

1. Serve NPC customers at register
2. Earn currency & XP
3. Level up & unlock abilities
4. Explore dungeons with other players
5. Craft items & trade
6. Join franchise & capture territory

---

🐛 Known Issues & Roadmaps

Security Audit Results (2026-02-14):

• 1 CRITICAL issue identified (race condition). (Note: missing admin auth has been resolved)
• 5 MEDIUM issues identified (rate limiting, JWT expiry, logging, etc.)
• See SECURITY_ROADMAP.md for details & fixes

Test Coverage Gaps:

• Socket handlers: ~70% (need 90%+)
• Database operations: ~85% (need 95%+)
• See TESTING_IMPROVEMENTS.md for P0 tests

Code Quality Improvements:

• Rate limiting scattered across files (need consolidation)
• Time units inconsistent (ms vs seconds)
• See CODE_QUALITY_ROADMAP.md for refactoring plan

---

🤝 Contributing

This is a learning/demonstration project. Contributions welcome!

Key Areas:

• Additional NPC types
• More abilities & skills
• Dungeon content
• UI/UX improvements
• Performance optimization
• Test coverage

---

📜 License

MIT License - See LICENSE file for details

---

🎉 Credits

Built with Claude Code during an overnight development session. A demonstration of rapid game development with AI assistance.

Technologies:

• Next.js, React, TypeScript
• Phaser 3, Socket.io
• PostgreSQL, Redis, Prisma
• Docker, TailwindCSS

---

🚀 Deployment

Docker Production

# Build production images
docker-compose -f docker-compose.prod.yml build

# Start production stack
docker-compose -f docker-compose.prod.yml up -d

# View logs
docker-compose -f docker-compose.prod.yml logs -f

# Stop
docker-compose -f docker-compose.prod.yml down

Manual Deployment

1. Build apps: npm run build
2. Set up PostgreSQL database
3. Run migrations: npm run prisma:migrate
4. Start server: npm start in apps/server
5. Serve web: Use your preferred static host (Vercel, Netlify, etc.)

---

📞 Support

• Issues: File on GitHub
• Questions: Check docs/ folder
• Admin Access: Default password admin123 (CHANGE IN PRODUCTION!)

---

Happy coding! May your customers be patient and your transactions profitable. 💰🎮