🎮 Frontier Arcade Portal

A distinguished game launcher platform for arcade cabinets, built with modern web technology.

The Frontier Arcade Portal is a full-featured game launcher and management system designed for Frontier Tower's arcade cabinets in downtown San Francisco. It provides a unified interface for launching web and Python games, complete with gamepad navigation, session tracking, and real-time system monitoring.

Platform Highlights:

• 🕹️ Gamepad-First Navigation - Optimized for arcade stick and button controls
• 🎯 Multi-Game Launcher - Web games (iframe), Python games (subprocess), extensible for more
• 📊 Admin Dashboard - Real-time health metrics, session analytics, system monitoring
• 🎨 Arcade-Optimized UI - High contrast, neon aesthetics, distance-viewable design
• 🏗️ Distinguished Engineering - Factory patterns, state management, event bus, comprehensive test coverage

---

🚀 Quick Start

Automated Setup

git clone https://github.com/frontiertower/frontier-arcade.git
cd frontier-arcade
bash setup_frontier_arcade.sh

The script installs uv, Python 3.12, creates virtual environments, and installs all dependencies.

Running the Portal

Terminal 1 - Backend API:

cd arcade-portal/api
source .venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 - Frontend UI:

cd arcade-portal/frontend
npm install  # first time only
npm run dev -- --port 3000 --host 0.0.0.0

Access:

• 🎮 Portal: http://localhost:3000
• 📊 Admin Dashboard: http://localhost:3000/admin
• 📚 API Docs: http://localhost:8000/docs
• 💚 Health Check: http://localhost:8000/api/v1/health

Testing

cd arcade-portal/frontend
npm test                    # Run full test suite (136 tests)
npm test -- --watch         # Watch mode for development

---

🏛️ Portal Architecture

Technology Stack

Frontend:

• SvelteKit - Fast, reactive framework with excellent DX
• TypeScript - Type safety and maintainability
• TailwindCSS 4 - Utility-first styling with custom design tokens
• Vitest - Lightning-fast unit testing (136 tests, 100% pattern coverage)

Backend:

• FastAPI - Modern Python API framework
• uvicorn - ASGI server for async Python
• Python 3.12 - Latest language features

Design System:

• Arcade-optimized color palette (Frontier purple + neon accents)
• Gamepad-first navigation with focus management
• Distance-viewable typography (larger scale)
• High-contrast UI for arcade cabinet environments

Design Patterns

The portal is built with production-grade engineering patterns:

Pattern	Purpose	Implementation
Factory	Game launcher creation	GameLauncherFactory creates WebGameLauncher or PythonGameLauncher based on game type
Repository	Data access layer	GameRepository with cache strategy for game metadata
Service Layer	Business logic	GameService orchestrates launchers, notifications, and events
Observer/Event Bus	Decoupled events	EventBus publishes game lifecycle events (launched, exited, errors)
State Management	Centralized state	Redux-inspired Store with middleware for logging and persistence
Cache Strategy	Performance	LRU and LocalStorage caching with TTL expiration

Test Coverage: 136 tests across 9 test suites covering all patterns and components.

Key Features

Game Management:

• Launch web games in fullscreen iframes with message passing
• Launch Python games via subprocess with session tracking
• Extensible launcher system - add Docker, WASM, or other game types
• Session management with start/stop lifecycle

Gamepad Navigation:

• D-pad/analog stick for grid navigation
• A button for selection, B button for back
• Focus manager with wraparound navigation
• Keyboard fallback for development

Admin Dashboard:

• Real-time API health monitoring
• Game launch statistics and error tracking
• Cache hit rates and performance metrics
• System status with visual indicators

Analytics & Monitoring:

• Event bus tracks all game launches, exits, and errors
• Analytics adapter for metrics collection
• Persistent game session history
• Repository pattern with caching for performance

File Structure

arcade-portal/
├── frontend/
│   ├── src/
│   │   ├── lib/
│   │   │   ├── patterns/
│   │   │   │   ├── factory/      # Game launcher factory
│   │   │   │   ├── store/        # State management
│   │   │   │   ├── events/       # Event bus
│   │   │   │   ├── repository/   # Data access
│   │   │   │   ├── service/      # Business logic
│   │   │   │   └── cache/        # Caching strategies
│   │   │   ├── components/       # UI components
│   │   │   └── game-integration/ # Web game manager
│   │   └── routes/
│   │       ├── +page.svelte      # Portal home
│   │       └── admin/            # Admin dashboard
│   └── tests/                    # 136 tests
└── api/
    └── app/
        ├── main.py               # FastAPI app
        ├── routes/               # API endpoints
        └── services/             # Game launch services

---

🎯 Game Collection

The portal launches four distinct games, each in its own submodule repository:

Game	Platform	Players	Genre	Launch Method
🟡 Pac-Man	Python + Pygame	1P	Classic Arcade	Python subprocess
🎨 Sketch Battles	Next.js + React	1v1	Social Drawing	Web (iframe)
🦕 Dino Blaster Runner	Python + Pygame	1P	Action Runner	Python subprocess
🏢 Tower Madness	Python + Pygame	1-2P	Elevator Sim	Python subprocess

Game Features:

• Pac-Man: Classic arcade mechanics with authentic ghost AI (~82k LOC)
• Sketch Battles: Real-time multiplayer drawing with Supabase backend (~15k LOC)
• Dino Blaster: Endless runner with bosses, power-ups, and combo scoring (~60k LOC)
• Tower Madness: Meta-game set in actual Frontier Tower SF with 19 floors (~50k LOC)

See individual game repositories for detailed setup, controls, and customization options.

---

🛠️ Development

Adding a New Game Type

The Factory Pattern makes it easy to add new game types (Docker, WASM, etc.):

1. Create a new launcher implementing IGameLauncher:

   // frontend/src/lib/patterns/factory/DockerGameLauncher.ts
   export class DockerGameLauncher implements IGameLauncher {
     readonly type = 'docker';
   
     async launch(game: Game, options?: LaunchOptions): Promise<void> {
       // Your Docker container launch logic
     }
   
     async stop(gameId: string): Promise<void> {
       // Cleanup logic
     }
   
     // Implement other interface methods...
   }

2. Register the launcher:

   // frontend/src/lib/patterns/factory/GameLauncherFactory.ts
   private registerDefaultLaunchers(): void {
     this.register('web', new WebGameLauncher());
     this.register('python', new PythonGameLauncher());
     this.register('docker', new DockerGameLauncher());  // Add this
   }

3. Add tests in factory.test.ts following existing patterns

4. Update API if backend changes are needed for the new launcher type

Project Structure

arcade-portal/
├── frontend/           # SvelteKit + TypeScript portal UI
│   ├── src/lib/patterns/  # Design patterns (factory, store, events, etc.)
│   └── tests/          # Vitest test suite (136 tests)
├── api/                # FastAPI backend for Python game launching
├── docs/               # Architecture and design documentation
│   ├── design/         # Design system, UI patterns
│   └── planning/       # Project roadmaps and status
└── [game-repos]/       # Git submodules for each game

Code Quality

• TypeScript: Strict mode enabled, no any types
• Tests: 136 tests across all patterns and components
• Patterns: Factory, Repository, Service Layer, Event Bus, State Management
• Linting: ESLint + Prettier for consistent code style
• Documentation: Inline JSDoc comments for all public APIs

---

🤝 Contributing

Portal Development

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for new functionality
4. Ensure all tests pass (npm test)
5. Update documentation as needed
6. Submit a pull request

Game Development

• Each game is in its own submodule repository
• See individual game READMEs for contribution guidelines
• Test on actual arcade hardware when possible

Design System

• Follow arcade-first design principles
• Maintain gamepad navigation support
• Ensure high contrast for distance viewing
• See docs/design/DESIGN_SYSTEM.md for guidelines

---

📚 Documentation

• Design System - UI/UX guidelines, components, patterns
• Event Bus - Observer pattern implementation
• Project Status - Current phase and roadmap
• Phase 4 Roadmap - Advanced features plan

---

Built with ♥ for the Frontier Tower community

A distinguished game launcher platform bringing modern engineering to retro arcade gaming