Darkraise
b5feb04604
- Consolidate docker-compose files: dev.yml builds locally, main uses pre-built images; remove redundant prod.yml and images.yml - Add docker-entrypoint.sh for database copy from network storage - Add SQLite performance tuning (PRAGMA optimizations, mmap, cache) - Add cache pre-warming for instant first page load - Enhance logging with OTEL-compatible JSON format and trace context - Simplify .env.example with clearer sections and fewer variables - Remove EXTERNAL_IMAGE_URLS env var (auto-read from FP preferences) - Hardcode container ports (use docker port mapping to customize) - Add /api/errors/stats endpoint for admin dashboard
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, 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
- Start with Project Overview
- Read Architecture Overview
- Follow Setup Guide
- Review Commands
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