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