Darkraise
c8083eb6b5
Implement activity analytics dashboard with real-time stats, charts, and user leaderboard. Add automated Ruffle update job for Flash emulator maintenance. Standardize datetime formatting across frontend/backend with ISO 8601 and user preferences. Enhance security with comprehensive input validation, rate limiting, and CSRF protection. Improve accessibility with ARIA labels, keyboard navigation, and screen reader support. Fix multiple security vulnerabilities including XSS, SQL injection risks, and session management issues.
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