dotcom-arcade/docs/08-development/README.md

Development Documentation

This directory contains comprehensive documentation for developers working on the Dotcom Arcade application.

Contents

1. Setup Guide - Complete development environment setup
2. Commands Reference - All npm commands for monorepo and services
3. Project Structure - Directory structure explained
4. Coding Standards - TypeScript conventions and style guide
5. Testing Guide - Testing approach and best practices
6. Debugging Guide - Debugging tips and troubleshooting
7. Common Pitfalls - Known issues and solutions
8. Upstream Sync - Merging changes from flashpoint-web
9. GitHub Mirror - Publishing to GitHub and GHCR
10. Demo Data - Made-up games for development and screenshots

Quick Start

# Install dependencies for all services
npm run install:all

# Start all services in development mode
npm run dev

# Run type checking across all services
npm run typecheck

# Build all services for production
npm run build

Development Workflow

1. Initial Setup: Follow the Setup Guide
2. Learn Commands: Review Commands Reference
3. Understand Structure: Read Project Structure
4. Follow Standards: Apply Coding Standards
5. Write Tests: Use Testing Guide
6. Debug Issues: Reference Debugging Guide
7. Avoid Pitfalls: Check Common Pitfalls

Architecture Overview

The project is a monorepo with two independent services:

• Backend (port 3100): REST API with Express + TypeScript (includes game service)
• Frontend (port 5173): React SPA with Vite + TypeScript

Each service can be developed, tested, and deployed independently. The game service is now integrated into the backend as the /game-proxy/* and /game-zip/* routes.

Getting Help

• Review existing documentation in this directory
• Check the main CLAUDE.md for project overview
• Consult service-specific docs in docs/03-backend and docs/04-frontend
• Review architecture documentation in docs/02-architecture

Contributing

When adding new features or fixing bugs:

1. Follow the coding standards outlined in this documentation
2. Write tests for new functionality
3. Update relevant documentation
4. Ensure all type checks pass (npm run typecheck)
5. Verify no build errors (npm run build)