dotcom-arcade/docs

Flashpoint Web - Technical Documentation

Complete technical documentation for the Flashpoint Web project, a self-hosted web application for browsing and playing games from the Flashpoint Archive.

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

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

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