Dotcom Arcade - Technical Documentation
Technical documentation for Dotcom Arcade, a self-hosted, Flash-era game portal for Flashpoint Ultimate.
Documentation Structure
01. Overview
- Project Overview - Introduction and key features
- Technology Stack - Complete technology stack
02. Architecture
- System Architecture - Complete system design
- Service Communication - Inter-service communication
- Data Flow Diagrams - Request/response flows
- Authentication Flow - Authentication and authorization
- Game Launch Flow - Game playing process
- Play Tracking Flow - Session tracking
03. Backend Service
- Backend Overview - Backend service introduction
- Architecture - Backend architecture patterns
- Configuration - Environment variables
- Services:
- Database Service - Flashpoint database management
- User Database Service - User database management
- Permission Cache Service - Permission caching
- Database:
- Schema - Complete database schema
04. Frontend Application
- Frontend Overview - Frontend application introduction
- Architecture - Frontend architecture patterns
- Components:
- Component Overview - Component organization
- Layout Components - AppShell, Header, Sidebar
- Game Components - Game browsing components
- Player Components - Game players
- Auth Components - Authentication UI
- UI Components - Shadcn UI library
- Views & Routing - All views and routes
- State Management:
- Zustand Stores - Client state
- React Query - Server state
- URL State - URL-based filters
- Custom Hooks - All custom hooks
- API Client - Axios client integration
- Player Implementation:
- Ruffle Player - Flash games
- HTML5 Player - HTML5 games
05. Game Service (Integrated into Backend)
- Game Service Overview - Game service introduction
- Architecture - Integrated single-service design
- Proxy Server - HTTP proxy (/game-proxy/*)
- GameZip Server - ZIP server (/game-zip/*)
- Legacy Server - Legacy content serving
- ZIP Manager - ZIP mounting
- MIME Types - MIME type handling
- HTML Polyfills - Game compatibility
- Configuration - Environment variables
06. API Reference
- API Overview - API documentation index
- Authentication API - Auth endpoints
- Games API - Game endpoints
- Users API - User management
- Roles API - Role & permission endpoints
- Playlists API - Playlist management
- Play Tracking API - Play session endpoints
- Platforms & Tags API - Filter endpoints
- Favorites API - Favorite games management
- Activities API - Activity logging
- Admin API - Admin endpoints
- Shared Playlists API - Playlist sharing
- Settings API - System settings
07. Design System
- Design System Overview - Design system introduction
- Theme System - Theme modes and colors
- Color Palette - All 22 colors
- Typography - Font sizes and weights
- Spacing & Layout - Spacing scale
- Components Library - UI components
- Icons - Lucide icons
- Responsive Design - Breakpoints
- Design Patterns - UI patterns
08. Development
- Setup Guide - Complete development setup
- Commands - All npm commands
- Project Structure - Directory structure
- Coding Standards - Code conventions
- Testing Guide - Testing approach
- Debugging - Debugging tips
- Common Pitfalls - Known issues
- Upstream Sync - Merging changes from flashpoint-web
- GitHub Mirror - Publishing to GitHub and GHCR
- Demo Data - Made-up games for development and screenshots
09. Deployment
- Deployment Overview - Deployment documentation
- Docker Deployment - Docker Compose setup
- Environment Variables - All env vars
- Upgrade Guide - Migration steps and release notes
- Health Checks - Health check endpoints
- Security Considerations - Security best practices
10. Features
- Authentication & Authorization - Complete auth system
- Game Browsing & Filtering - Search and filters
- Game Playing - Playing Flash/HTML5 games
- Play Session Tracking - Play tracking
- Playlists & Favorites - Playlist management
- User Management - User administration
- Role & Permissions - RBAC system
- Activity Logging - Audit logging
- System Settings - System configuration
- Date/Time Formatting - Date display formatting
- Maintenance Mode - Restricting access during updates
- Discovery Portal - Portal layout, homepage discovery, game page and mature content filter
- Streaming - Games streamed from the server
- Proxy Sign-In - Sign-in through Authentik, Authelia or oauth2-proxy
- Game Saves - Saves kept on players' accounts
11. Diagrams
- Diagrams Overview - Visualization and flows
12. Reference
- Database Schema Reference - Complete schema
- Type Definitions - All TypeScript types
- Glossary - Terms and definitions
- External Dependencies - Third-party libraries
- Security Measures - Security overview
- CORS Security Decision - CORS policy rationale
- Database Indexes - Index optimization
13. Security
- Directory Traversal Protection - Path security