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, purpose, and key features
Architecture Overview - High-level system architecture
Technology Stack - Complete technology stack
Getting Started - Quick start guide for developers

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
Services:
- Database Service - Flashpoint database management
- User Database Service - User database management
- Auth Service - Authentication & token management
- User Service - User CRUD operations
- Role Service - Role & permission management
- Game Service - Game metadata queries
- Play Tracking Service - Play session tracking
- Activity Service - Activity logging
Routes: API Routes - All API endpoints
Middleware:
- Authentication - Auth middleware
- RBAC - Permission checking
- Error Handling - Error handler
- Activity Logger - Activity logging
Database:
- Schema - Complete database schema
- Migrations - Migration system
- Data Models - TypeScript types
Configuration - Environment variables

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: Views & Routing - All views and routes
State Management:
- Zustand Stores - Client state
- React Query - Server state
- URL State - URL-based filters
Hooks: Custom Hooks - All custom hooks
API Integration: API Client - Axios client
Player Implementation:
- Ruffle Player - Flash games
- HTML5 Player - HTML5 games

05. Game Service

Game Service Overview - Game service introduction
Architecture - Dual-server design
Proxy Server - HTTP proxy (port 22500)
GameZip Server - ZIP server (port 22501)
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
Request/Response Examples - Complete examples

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

Docker Deployment - Docker Compose setup
Production Setup - Production configuration
Environment Variables - All env vars
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

11. Diagrams

System Architecture - Overall architecture
Authentication Flow - Auth flow
Game Launch Flow - Game launch
Play Tracking Flow - Play tracking
Service Communication - Inter-service comm
Database Schema - Database ERD
Component Hierarchy - Frontend components

12. Reference

Database Schema Reference - Complete schema
Type Definitions - All TypeScript types
Glossary - Terms and definitions
External Dependencies - Third-party libraries

Quick Links

For New Developers

For Frontend Developers

For Backend Developers

For API Integration

Contributing

When updating documentation:

Keep code examples up to date with implementation
Include file paths for reference
Use Mermaid for diagrams where possible
Follow the existing structure and style

Documentation Version

This documentation is for Flashpoint Web v1.0.0 (current development version).

Last updated: 2026-01-18