Darkraise
7d3d64903f
- Eliminate `new Promise(async ...)` anti-pattern in GameDataDownloader - Add TOCTOU-safe transactions in DomainService, FavoritesService, DownloadManager, and UserService (cascading delete) - Add path traversal protection in PlaylistService (UUID validation) - Add Zip Slip protection and backup restore in RuffleService - Escape LIKE wildcards in GameService search queries - Cache ZIP entry metadata to avoid re-reading entries on every lookup - Fix login lockout query to check username/IP independently - Cache null values in CachedSystemSettingsService to avoid repeated DB queries for missing keys - Chunk MetadataSyncService upserts to stay under SQLite variable limit - Add GitHub stars endpoint caching (15min TTL) to respect rate limits - Deduplicate concurrent proxy cache writes via pending-write tracking - Prevent infinite retry loop in DatabaseService syncAndReload - Fix `useEffect` dependency issues with callback refs in MaintenanceGuard, useLazyLoad, useSwipeGesture, GameDetailView - Handle async errors in MaintenancePage polling and MetadataUpdateCard - Add null-safe guards for dashboard statistics rendering - Validate settings category, timeRange, and batch size limits - Sanitize error messages to avoid leaking internals to clients - Stream error log file reads instead of loading entire file into memory - Narrow `SELECT u.*` to explicit columns in AuthService - Remove `themeColor`/`surfaceColor` from auth response payload - Fix "playlistGames" typo in UserPlaylistDetailView - Tighten `isApiError` type guard to require status/code/response - Add `maxContentLength` to external HTTP requests - Add null-byte rejection in proxy path validation - Use URL constructor for safe logo URL derivation - Add shared playlist validation middleware to game validate endpoint - Add `res.destroyed` checks in GameZipServer before/after async lookup - Proper listener cleanup in proxy `collectRequestBody` - Add `.unref()` to PermissionCache cleanup interval - Add `SharedPlaylistView` auth gate for query enablement
Flashpoint Web
A modern web interface for the Flashpoint Archive
Browse and play 200,000+ preserved Flash games and animations directly in your browser.
Features | Quick Start | Docker | Documentation | Contributing
What is Flashpoint Web?
Flashpoint Web is a self-hosted web application for accessing your local Flashpoint Archive collection. It provides a modern, browser-based alternative to the Flashpoint Launcher with multi-user support, play tracking, and an intuitive interface.
Key Features
- Browse & Search - Fast search across 200,000+ games with advanced filtering by platform, developer, tags, and more
- Play in Browser - Flash games via Ruffle emulator, HTML5 games natively
- Multi-User Support - Individual accounts with role-based permissions (admin, moderator, user, guest)
- Play Tracking - Track playtime, completion status, and view play statistics
- Playlists & Favorites - Organize your game collection with custom playlists
- 22 Theme Palettes - Customizable dark/light modes with multiple color schemes
- Responsive Design - Works on desktop and mobile devices
- Database Hot-Reload - Automatically syncs when Flashpoint Launcher updates metadata
Architecture
Flashpoint Web consists of two independent services:
| Service | Port | Description |
|---|---|---|
| Backend | 3100 | REST API for metadata, users, auth, and game content serving |
| Frontend | 5173 | React web application |
Game content is served directly by the backend via /game-proxy/* and
/game-zip/* routes, enabling efficient file serving and ZIP archive mounting.
Quick Start
Prerequisites
- Node.js 20+ and npm 9+
- Flashpoint Archive installed locally
Installation
# Clone the repository
git clone https://github.com/darkraise/flashpoint-web.git
cd flashpoint-web
# Install dependencies for all services
npm run install:all
Configuration
1. Backend (backend/.env)
cp backend/.env.example backend/.env
Edit backend/.env:
# Required
FLASHPOINT_PATH=D:/Flashpoint
JWT_SECRET=your-secure-random-string
# Optional
DOMAIN=http://localhost:5173
LOG_LEVEL=info
Note: All database, asset, and game content paths are automatically derived from
FLASHPOINT_PATH. Frontend requires no.envfile for local development - API calls are proxied through Vite.
Run Development Servers
# Start all services concurrently
npm run dev
# Or start individually
npm run dev:backend # http://localhost:3100
npm run dev:frontend # http://localhost:5173
Open http://localhost:5173 in your browser.
Docker Deployment
For production or easier setup, use Docker Compose:
# Set required environment variables
export FLASHPOINT_HOST_PATH=/path/to/Flashpoint # Linux/Mac
export JWT_SECRET="your-secure-secret-key" # Required for auth
# Windows PowerShell
$env:FLASHPOINT_HOST_PATH="D:\Flashpoint"
$env:JWT_SECRET="your-secure-secret-key"
# Start all services (uses pre-built images)
docker compose up -d
# Or build locally for development
docker compose -f docker-compose.dev.yml up -d --build
# View logs
docker compose logs -f
Default ports:
| Service | URL |
|---|---|
| Frontend | http://localhost (port 80) |
| Backend API | http://localhost:3100 |
| Game Content Routes | http://localhost:3100/game-proxy/* and /game-zip/* |
See Docker Deployment Guide for advanced configuration.
Development Commands
| Command | Description |
|---|---|
npm run dev |
Start all services in development mode |
npm run build |
Build all services for production |
npm run typecheck |
Run TypeScript type checking |
npm run format |
Format code with Prettier |
npm run clean |
Remove build artifacts and node_modules |
See Commands Reference for the complete list.
Documentation
Comprehensive documentation is available in the docs/ directory:
Getting Started
- Project Overview - What is Flashpoint Web
- Setup Guide - Complete development setup
- Commands Reference - All available commands
Architecture
- System Architecture - Service design overview
- Authentication Flow - JWT-based auth system
- Game Launch Flow - How games are served
Services
- Backend - REST API documentation
- Frontend - React application guide
- Game Service - File serving architecture
API Reference
Deployment
Features
Technology Stack
Backend
|
Frontend
|
See Technology Stack for detailed explanations of each choice.
Troubleshooting
Common Issues
Port already in use:
# Find and kill process on port
lsof -i :3100 # Linux/Mac
netstat -ano | findstr :3100 # Windows
Database not found:
- Verify
FLASHPOINT_PATHpoints to a valid Flashpoint installation - Check that
$FLASHPOINT_PATH/Data/flashpoint.sqliteexists
Ruffle not loading:
cd frontend
npm run copy-ruffle
Games not loading:
- Ensure backend is running on port 3100
- Check backend logs:
npm run dev:backend - Verify game content routes are accessible at
/game-proxy/*and/game-zip/*
See Common Pitfalls for more solutions.
Contributing
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and ensure tests pass:
npm run typecheck - Commit your changes following our commit guidelines
- Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
Please read our Contributing Guide for detailed instructions, coding standards, and development setup.
Related Projects
- Flashpoint Archive - The game preservation project
- Flashpoint Launcher - Official desktop launcher
- Ruffle - Flash Player emulator
License
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
Acknowledgments
- Flashpoint Team - For preserving web gaming history
- Ruffle Contributors - For making Flash playable in modern browsers
- Community - For testing, feedback, and contributions