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 three independent services:

Service	Port	Description
Backend	3100	REST API for game metadata, users, and authentication
Frontend	5173	React web application
Game Service	22500/22501	File serving proxy and ZIP archive server

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 and asset paths are automatically derived from FLASHPOINT_PATH.

2. Game Service (game-service/.env)

cp game-service/.env.example game-service/.env

# Required
FLASHPOINT_PATH=D:/Flashpoint

# Optional
LOG_LEVEL=info
EXTERNAL_FALLBACK_URLS=http://infinity.flashpointarchive.org/Flashpoint/Legacy/htdocs

Note: Frontend requires no .env file 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
npm run dev:game-service # http://localhost:22500

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 Proxy | http://localhost:22500 | | GameZip Server | http://localhost:22501 |

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

• Authentication API
• Games API
• Playlists API
• Full API Reference

Deployment

• Docker Deployment
• Production Setup
• Environment Variables

Features

• Authentication & Authorization
• Game Browsing & Filtering
• Play Session Tracking
• All Features

Technology Stack

Backend Express 4.18 BetterSqlite3 12.6 JWT + bcrypt Winston logging Zod validation

Frontend React 18.3 + TypeScript TanStack Query 5.28 Zustand 4.5 Shadcn UI + Radix Ruffle Flash Emulator

Game Service Express 4.18 node-stream-zip 1.15 Winston logging CDN fallback support

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_PATH points to a valid Flashpoint installation
• Check that $FLASHPOINT_PATH/Data/flashpoint.sqlite exists

Ruffle not loading:

cd frontend
npm run copy-ruffle

Games not loading:

• Ensure game-service is running (ports 22500/22501)
• Check game-service logs: npm run dev:game-service

See Common Pitfalls for more solutions.

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and ensure tests pass: npm run typecheck
4. Commit your changes following our commit guidelines
5. Push to the branch: git push origin feature/amazing-feature
6. 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

---

Documentation | Report Bug | Request Feature