chore: add readme and update documents

2026-02-03 10:42:28 +07:00
parent 10d6e3a85c
commit da7c965491
25 changed files with 1500 additions and 434 deletions
@@ -0,0 +1,75 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: '[BUG] '
+labels: bug, triage
+assignees: ''
+---
+
+## Bug Description
+
+<!-- A clear and concise description of what the bug is. -->
+
+## Steps to Reproduce
+
+1. Go to '...'
+2. Click on '...'
+3. Scroll down to '...'
+4. See error
+
+## Expected Behavior
+
+<!-- A clear and concise description of what you expected to happen. -->
+
+## Actual Behavior
+
+<!-- A clear and concise description of what actually happened. -->
+
+## Screenshots
+
+<!-- If applicable, add screenshots to help explain your problem. -->
+
+## Environment
+
+**Desktop:**
+- OS: [e.g., Windows 11, macOS 14, Ubuntu 22.04]
+- Browser: [e.g., Chrome 120, Firefox 121, Safari 17]
+- Node.js version: [e.g., 20.11.0]
+
+**Flashpoint Web Version:**
+- Backend version: [e.g., commit hash or version]
+- Frontend version: [e.g., commit hash or version]
+
+**Flashpoint Archive:**
+- Flashpoint version: [e.g., Flashpoint 12]
+- Installation type: [e.g., Infinity, Ultimate]
+
+## Logs
+
+<!-- If applicable, paste relevant error logs here. -->
+
+<details>
+<summary>Backend Logs</summary>
+
+```
+Paste backend logs here
+```
+
+</details>
+
+<details>
+<summary>Browser Console</summary>
+
+```
+Paste browser console errors here
+```
+
+</details>
+
+## Additional Context
+
+<!-- Add any other context about the problem here. -->
+
+## Possible Solution
+
+<!-- If you have ideas on how to fix this, please share. -->
@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://github.com/YOUR_USERNAME/flashpoint-web/tree/master/docs
+    about: Check the documentation before opening an issue
+  - name: Flashpoint Archive
+    url: https://flashpointarchive.org/
+    about: For issues with Flashpoint itself (not this web interface)
+  - name: Ruffle Flash Emulator
+    url: https://github.com/ruffle-rs/ruffle/issues
+    about: For Flash emulation issues, report to the Ruffle project
@@ -0,0 +1,56 @@
+---
+name: Documentation
+about: Report documentation issues or suggest improvements
+title: '[DOCS] '
+labels: documentation
+assignees: ''
+---
+
+## Documentation Issue Type
+
+- [ ] Missing documentation
+- [ ] Incorrect/outdated information
+- [ ] Unclear explanation
+- [ ] Typo/grammar
+- [ ] Broken links
+- [ ] Missing code examples
+- [ ] Other: ___________
+
+## Location
+
+<!-- Where is the documentation issue? -->
+
+**File path:** `docs/...`
+
+**URL (if applicable):**
+
+**Section/Heading:**
+
+## Current Content
+
+<!-- Quote or describe the current documentation. -->
+
+```
+Current text here...
+```
+
+## Problem Description
+
+<!-- What's wrong with the current documentation? -->
+
+## Suggested Improvement
+
+<!-- How should it be changed? -->
+
+```
+Suggested text here...
+```
+
+## Additional Context
+
+<!-- Any other information that might help. -->
+
+## Checklist
+
+- [ ] I have checked that this isn't already documented elsewhere
+- [ ] I have verified the information I'm suggesting is accurate
@@ -0,0 +1,77 @@
+---
+name: Enhancement
+about: Suggest an improvement to existing functionality
+title: '[ENHANCEMENT] '
+labels: enhancement
+assignees: ''
+---
+
+## Enhancement Description
+
+<!-- A clear and concise description of the enhancement you're proposing. -->
+
+## Current Behavior
+
+<!-- Describe how the feature currently works. -->
+
+## Proposed Improvement
+
+<!-- Describe how you'd like the feature to work instead. -->
+
+## Benefits
+
+<!-- Explain the benefits of this enhancement. -->
+
+-
+-
+-
+
+## Affected Area
+
+<!-- Which part of the application does this affect? -->
+
+- [ ] UI/UX
+- [ ] Performance
+- [ ] API
+- [ ] Database
+- [ ] Authentication
+- [ ] Game Player
+- [ ] Search/Filtering
+- [ ] Playlists
+- [ ] Admin Panel
+- [ ] Other: ___________
+
+## Affected Services
+
+- [ ] Backend
+- [ ] Frontend
+- [ ] Game Service
+- [ ] Documentation
+
+## Breaking Changes
+
+<!-- Will this enhancement require breaking changes? -->
+
+- [ ] Yes (describe below)
+- [ ] No
+- [ ] Unknown
+
+<!-- If yes, describe what would break: -->
+
+## Implementation Suggestions
+
+<!-- Optional: Share ideas on how to implement this. -->
+
+## Screenshots / Mockups
+
+<!-- If applicable, add visuals showing the proposed enhancement. -->
+
+## Related Issues
+
+<!-- Link any related issues or PRs. -->
+
+- #
+
+## Additional Context
+
+<!-- Add any other context here. -->
@@ -0,0 +1,71 @@
+---
+name: Feature Request
+about: Suggest a new feature for the project
+title: '[FEATURE] '
+labels: enhancement, feature-request
+assignees: ''
+---
+
+## Feature Description
+
+<!-- A clear and concise description of the feature you'd like. -->
+
+## Problem Statement
+
+<!-- Is this feature related to a problem? Describe it. -->
+<!-- Example: "I'm frustrated when..." -->
+
+## Proposed Solution
+
+<!-- Describe the solution you'd like. -->
+
+## User Story
+
+<!-- Optional: Describe the feature from a user's perspective. -->
+<!-- Example: "As a [type of user], I want [goal] so that [benefit]." -->
+
+As a **[user type]**, I want **[goal/desire]** so that **[benefit/value]**.
+
+## Use Cases
+
+<!-- List specific scenarios where this feature would be useful. -->
+
+1.
+2.
+3.
+
+## Mockups / Examples
+
+<!-- If applicable, add mockups, wireframes, or examples from other apps. -->
+
+## Alternatives Considered
+
+<!-- Describe any alternative solutions or features you've considered. -->
+
+## Implementation Ideas
+
+<!-- Optional: Share any thoughts on how this could be implemented. -->
+
+### Affected Services
+
+- [ ] Backend
+- [ ] Frontend
+- [ ] Game Service
+- [ ] Documentation
+
+### Estimated Complexity
+
+- [ ] Small (few hours)
+- [ ] Medium (1-3 days)
+- [ ] Large (1+ week)
+- [ ] Unknown
+
+## Additional Context
+
+<!-- Add any other context, screenshots, or references here. -->
+
+## Checklist
+
+- [ ] I have searched existing issues to ensure this isn't a duplicate
+- [ ] I have provided clear use cases for this feature
+- [ ] I have considered how this fits with existing functionality
@@ -0,0 +1,38 @@
+---
+name: Question
+about: Ask a question about the project
+title: '[QUESTION] '
+labels: question
+assignees: ''
+---
+
+## Question
+
+<!-- What would you like to know? -->
+
+## Context
+
+<!-- Provide any relevant context for your question. -->
+
+## What I've Tried
+
+<!-- What have you already looked at or tried? -->
+
+- [ ] Read the documentation at `docs/`
+- [ ] Searched existing issues
+- [ ] Checked the README
+- [ ] Other: ___________
+
+## Related Documentation
+
+<!-- Link any docs you've already reviewed. -->
+
+## Environment (if relevant)
+
+- OS:
+- Node.js version:
+- Browser:
+
+## Additional Information
+
+<!-- Any other details that might help answer your question. -->
@@ -0,0 +1,97 @@
+## Description
+
+<!-- Provide a brief description of the changes in this PR. -->
+
+## Related Issue
+
+<!-- Link the issue this PR addresses. Use "Closes #123" to auto-close the issue. -->
+
+Closes #
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Enhancement (improvement to existing functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+- [ ] Performance improvement
+- [ ] Test update
+
+## Changes Made
+
+<!-- List the main changes in this PR. -->
+
+-
+-
+-
+
+## Screenshots
+
+<!-- If applicable, add screenshots showing the changes. -->
+
+| Before | After |
+|--------|-------|
+|        |       |
+
+## Testing
+
+<!-- Describe how you tested your changes. -->
+
+### Test Steps
+
+1.
+2.
+3.
+
+### Test Results
+
+- [ ] All existing tests pass
+- [ ] New tests added for new functionality
+- [ ] Manual testing completed
+
+## Checklist
+
+### Code Quality
+
+- [ ] My code follows the project's coding standards
+- [ ] I have performed a self-review of my code
+- [ ] I have commented my code where necessary
+- [ ] My changes generate no new warnings or errors
+
+### Testing
+
+- [ ] I have run `npm run typecheck` and it passes
+- [ ] I have run the relevant tests
+- [ ] I have tested my changes manually
+
+### Documentation
+
+- [ ] I have updated the documentation accordingly
+- [ ] I have updated the CHANGELOG (if applicable)
+
+### Git
+
+- [ ] My commits follow the commit message guidelines
+- [ ] I have rebased on the latest `master` branch
+
+## Services Affected
+
+- [ ] Backend
+- [ ] Frontend
+- [ ] Game Service
+- [ ] Documentation
+- [ ] CI/CD
+
+## Breaking Changes
+
+<!-- If this PR introduces breaking changes, describe them and the migration path. -->
+
+## Additional Notes
+
+<!-- Any additional information reviewers should know. -->
+
+## Reviewer Notes
+
+<!-- Specific areas you'd like reviewers to focus on. -->
@@ -302,47 +302,42 @@ Independent Node.js service that replaces the original Go-based Flashpoint Game
 Required variables:

 ```bash
+# Required
 FLASHPOINT_PATH=D:/Flashpoint
-FLASHPOINT_DB_PATH=D:/Flashpoint/Data/flashpoint.sqlite
-FLASHPOINT_HTDOCS_PATH=D:/Flashpoint/Legacy/htdocs
-FLASHPOINT_IMAGES_PATH=D:/Flashpoint/Data/Images
-FLASHPOINT_LOGOS_PATH=D:/Flashpoint/Data/Logos
-FLASHPOINT_PLAYLISTS_PATH=D:/Flashpoint/Data/Playlists
-FLASHPOINT_GAMES_PATH=D:/Flashpoint/Data/Games
+JWT_SECRET=your-secure-random-string

-# Game service URLs (separate service)
-GAME_SERVICE_PROXY_URL=http://localhost:22500
-GAME_SERVICE_GAMEZIP_URL=http://localhost:22501
-
-# Frontend origin for CORS
+# Optional
 DOMAIN=http://localhost:5173
+GAME_SERVICE_HOST=localhost
+LOG_LEVEL=info
 ```

-Optional: JWT*SECRET, REDIS_ENABLED, LOG_LEVEL, RATE_LIMIT*\*
+> **Note:** All paths (database, images, logos, htdocs, games) are automatically derived from `FLASHPOINT_PATH`. You only need to set the base Flashpoint installation path.

-See `backend/.env.example` for complete configuration options.
+See `backend/.env.example` for complete configuration options including Redis, rate limiting, SQLite optimization, and OpenTelemetry settings.

 ### Game Service (.env)

 ```bash
-PROXY_PORT=22500
-GAMEZIPSERVER_PORT=22501
+# Required
 FLASHPOINT_PATH=D:/Flashpoint
-FLASHPOINT_HTDOCS_PATH=D:/Flashpoint/Legacy/htdocs
-FLASHPOINT_GAMES_PATH=D:/Flashpoint/Data/Games
-EXTERNAL_FALLBACK_URLS=http://infinity.flashpointarchive.org/Flashpoint/Legacy/htdocs,http://infinity.unstable.life/Flashpoint/Legacy/htdocs/
+
+# Optional
 LOG_LEVEL=info
+EXTERNAL_FALLBACK_URLS=http://infinity.flashpointarchive.org/Flashpoint/Legacy/htdocs
 ```

+> **Note:** All paths (htdocs, games) are automatically derived from `FLASHPOINT_PATH`.
+
 ### Frontend

-Environment variables are injected at build time via Vite:
+The frontend does not require environment variables for local development. API calls are proxied through Vite to the backend.

 ```bash
-VITE_API_URL=http://localhost:3100
+VITE_APP_VERSION=1.0.0  # Optional: displayed in settings
 ```

-Vite proxy configuration in `vite.config.ts` handles `/api/*` and `/proxy/*` routing to backend.
+Vite proxy configuration in `vite.config.ts` handles `/api/*` routing to backend. In production, Nginx proxies API requests to the backend container.

 ## Database Schema

@@ -0,0 +1,476 @@
+# Contributing to Flashpoint Web
+
+Thank you for your interest in contributing to Flashpoint Web! This document provides guidelines and instructions for contributing to this project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How to Contribute](#how-to-contribute)
+- [Pull Request Process](#pull-request-process)
+- [Coding Standards](#coding-standards)
+- [Commit Guidelines](#commit-guidelines)
+- [Testing](#testing)
+- [Documentation](#documentation)
+- [Community](#community)
+
+## Code of Conduct
+
+### Our Pledge
+
+We are committed to providing a welcoming and inspiring community for all. By participating in this project, you agree to:
+
+- Be respectful and inclusive
+- Accept constructive criticism gracefully
+- Focus on what is best for the community
+- Show empathy towards other community members
+
+### Unacceptable Behavior
+
+- Harassment, discrimination, or offensive comments
+- Trolling or insulting/derogatory comments
+- Public or private harassment
+- Publishing others' private information without permission
+
+## Getting Started
+
+### Prerequisites
+
+Before contributing, ensure you have:
+
+- [Node.js](https://nodejs.org/) 20.0.0 or higher
+- [npm](https://www.npmjs.com/) 9.0.0 or higher
+- [Git](https://git-scm.com/)
+- [Flashpoint Archive](https://flashpointarchive.org/) installed locally
+- A code editor (VS Code recommended)
+
+### Fork and Clone
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/flashpoint-web.git
+   cd flashpoint-web
+   ```
+3. **Add upstream remote**:
+   ```bash
+   git remote add upstream https://github.com/ORIGINAL_OWNER/flashpoint-web.git
+   ```
+
+## Development Setup
+
+### Quick Setup
+
+```bash
+# Install all dependencies
+npm run install:all
+
+# Copy environment files
+cp backend/.env.example backend/.env
+cp frontend/.env.example frontend/.env
+cp game-service/.env.example game-service/.env
+
+# Edit .env files with your Flashpoint paths
+# See docs/08-development/setup-guide.md for details
+
+# Start development servers
+npm run dev
+```
+
+### Verify Setup
+
+```bash
+# Run type checking
+npm run typecheck
+
+# Run tests
+cd backend && npm test
+cd ../frontend && npm test
+cd ../game-service && npm test
+```
+
+For detailed setup instructions, see [Setup Guide](docs/08-development/setup-guide.md).
+
+## How to Contribute
+
+### Reporting Bugs
+
+Before reporting a bug:
+1. Search [existing issues](https://github.com/OWNER/flashpoint-web/issues) to avoid duplicates
+2. Use the [Bug Report template](.github/ISSUE_TEMPLATE/bug_report.md)
+3. Include:
+   - Clear description of the issue
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Environment details (OS, Node version, browser)
+   - Screenshots or logs if applicable
+
+### Suggesting Features
+
+1. Check if the feature has already been requested
+2. Use the [Feature Request template](.github/ISSUE_TEMPLATE/feature_request.md)
+3. Explain the use case and benefits
+4. Consider how it fits with existing features
+
+### Contributing Code
+
+1. **Find an issue** to work on or create one
+2. **Comment on the issue** to let others know you're working on it
+3. **Create a branch** from `master`
+4. **Make your changes** following our coding standards
+5. **Write tests** for new functionality
+6. **Submit a pull request**
+
+### First-Time Contributors
+
+Look for issues labeled:
+- `good first issue` - Simple issues for newcomers
+- `help wanted` - Issues where we need community help
+- `documentation` - Documentation improvements
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Sync with upstream**:
+   ```bash
+   git fetch upstream
+   git rebase upstream/master
+   ```
+
+2. **Run all checks**:
+   ```bash
+   npm run typecheck
+   npm run format:check
+   cd backend && npm test
+   ```
+
+3. **Update documentation** if needed
+
+### PR Requirements
+
+- [ ] Branch is up-to-date with `master`
+- [ ] Code follows project coding standards
+- [ ] All tests pass
+- [ ] TypeScript has no errors
+- [ ] Documentation is updated (if applicable)
+- [ ] Commit messages follow guidelines
+- [ ] PR description explains the changes
+
+### Branch Naming
+
+Use descriptive branch names:
+```
+feature/add-playlist-export
+fix/game-search-pagination
+docs/update-api-reference
+refactor/auth-service-cleanup
+```
+
+### PR Title Format
+
+```
+type: short description
+
+Examples:
+feat: add game export to playlist
+fix: resolve pagination bug in game search
+docs: update Docker deployment guide
+refactor: simplify authentication middleware
+```
+
+## Coding Standards
+
+### TypeScript
+
+- Use TypeScript for all code
+- Enable strict mode
+- Define interfaces for all data structures
+- Avoid `any` type - use `unknown` if type is truly unknown
+
+```typescript
+// Good
+interface GameFilters {
+  platform?: string;
+  search?: string;
+  limit: number;
+}
+
+function searchGames(filters: GameFilters): Promise<Game[]> {
+  // ...
+}
+
+// Avoid
+function searchGames(filters: any): Promise<any> {
+  // ...
+}
+```
+
+### React Components
+
+- Use functional components with hooks
+- Define prop types with TypeScript interfaces
+- Keep components focused and single-purpose
+
+```typescript
+// Good
+interface GameCardProps {
+  game: Game;
+  onPlay: (id: string) => void;
+}
+
+export function GameCard({ game, onPlay }: GameCardProps) {
+  return (
+    <Card onClick={() => onPlay(game.id)}>
+      <CardTitle>{game.title}</CardTitle>
+    </Card>
+  );
+}
+```
+
+### API Endpoints
+
+- Use RESTful conventions
+- Add typed API methods to `frontend/src/lib/api.ts`
+- Never use raw `fetch()` for backend calls
+
+```typescript
+// In api.ts
+export const gamesApi = {
+  getById: async (id: string): Promise<Game> => {
+    const { data } = await api.get<ApiResponse<Game>>(`/games/${id}`);
+    return data.data;
+  },
+};
+
+// In component - CORRECT
+const game = await gamesApi.getById(id);
+
+// In component - WRONG (no auth headers)
+const response = await fetch(`/api/games/${id}`);
+```
+
+### Styling
+
+- Use Tailwind CSS utility classes
+- Follow existing component patterns
+- Use Shadcn UI components when available
+
+### File Organization
+
+```
+src/
+├── components/     # Reusable UI components
+│   ├── ui/         # Base UI components (Shadcn)
+│   └── [domain]/   # Domain-specific components
+├── views/          # Page components
+├── lib/            # Utilities and API client
+├── hooks/          # Custom React hooks
+├── store/          # Zustand stores
+└── types/          # TypeScript type definitions
+```
+
+## Commit Guidelines
+
+### Commit Message Format
+
+```
+type(scope): subject
+
+body (optional)
+
+footer (optional)
+```
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation changes |
+| `style` | Code style changes (formatting, semicolons) |
+| `refactor` | Code refactoring |
+| `test` | Adding or updating tests |
+| `chore` | Maintenance tasks |
+| `perf` | Performance improvements |
+
+### Examples
+
+```bash
+feat(games): add advanced search filters
+
+- Add platform filter dropdown
+- Add year range selector
+- Update API to support new parameters
+
+Closes #123
+
+---
+
+fix(auth): resolve token refresh race condition
+
+Multiple simultaneous requests could trigger multiple refresh
+calls. Added mutex lock to prevent duplicate refreshes.
+
+---
+
+docs: update API reference for v2 endpoints
+```
+
+### Commit Best Practices
+
+- Keep commits atomic (one logical change per commit)
+- Write meaningful commit messages
+- Reference issues when applicable (`Fixes #123`, `Closes #456`)
+
+## Testing
+
+### Backend Tests
+
+```bash
+cd backend
+npm test              # Run all tests
+npm test -- --watch   # Watch mode
+npm test -- --coverage # Coverage report
+```
+
+### Frontend Tests
+
+```bash
+cd frontend
+npm test              # Run all tests
+npm test -- --ui      # Open Vitest UI
+```
+
+### Writing Tests
+
+- Write tests for new features
+- Include edge cases
+- Mock external dependencies
+
+```typescript
+// Example test
+import { describe, it, expect, vi } from 'vitest';
+import { GameService } from './GameService';
+
+describe('GameService', () => {
+  it('should return games matching search query', async () => {
+    const games = await GameService.search({ query: 'mario' });
+
+    expect(games).toHaveLength(10);
+    expect(games[0].title).toContain('Mario');
+  });
+
+  it('should handle empty results gracefully', async () => {
+    const games = await GameService.search({ query: 'nonexistent12345' });
+
+    expect(games).toHaveLength(0);
+  });
+});
+```
+
+## Documentation
+
+### When to Update Docs
+
+Update documentation when you:
+- Add new features
+- Change API endpoints
+- Modify configuration options
+- Change architecture or patterns
+
+### Documentation Structure
+
+```
+docs/
+├── 01-overview/        # Project introduction
+├── 02-architecture/    # System design
+├── 03-backend/         # Backend service docs
+├── 04-frontend/        # Frontend service docs
+├── 05-game-service/    # Game service docs
+├── 06-api-reference/   # API documentation
+├── 07-design-system/   # UI/UX guidelines
+├── 08-development/     # Development guides
+├── 09-deployment/      # Deployment guides
+├── 10-features/        # Feature documentation
+└── 12-reference/       # Reference materials
+```
+
+### Documentation Standards
+
+- Use clear, concise language
+- Include code examples
+- Keep content up-to-date with code changes
+- Add diagrams for complex concepts
+
+## Project Structure
+
+```
+flashpoint-web/
+├── backend/           # Express REST API
+│   ├── src/
+│   │   ├── routes/    # API route handlers
+│   │   ├── services/  # Business logic
+│   │   ├── middleware/# Express middleware
+│   │   └── utils/     # Utility functions
+│   └── package.json
+│
+├── frontend/          # React application
+│   ├── src/
+│   │   ├── components/# UI components
+│   │   ├── views/     # Page components
+│   │   ├── lib/       # API client & utilities
+│   │   ├── hooks/     # Custom hooks
+│   │   └── store/     # State management
+│   └── package.json
+│
+├── game-service/      # Game file server
+│   ├── src/
+│   │   ├── servers/   # HTTP servers
+│   │   └── utils/     # Utilities
+│   └── package.json
+│
+├── docs/              # Documentation
+└── package.json       # Root package
+```
+
+## Community
+
+### Getting Help
+
+- Check the [documentation](docs/)
+- Search [existing issues](https://github.com/OWNER/flashpoint-web/issues)
+- Join discussions in issues or PRs
+
+### Communication
+
+- Be patient - maintainers are volunteers
+- Provide context and details in discussions
+- Be open to feedback and alternative approaches
+
+## Recognition
+
+Contributors are recognized in:
+- GitHub contributors list
+- Release notes for significant contributions
+- README acknowledgments section
+
+---
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Install dependencies | `npm run install:all` |
+| Start dev servers | `npm run dev` |
+| Type check | `npm run typecheck` |
+| Format code | `npm run format` |
+| Run backend tests | `cd backend && npm test` |
+| Run frontend tests | `cd frontend && npm test` |
+| Build all | `npm run build` |
+
+---
+
+Thank you for contributing to Flashpoint Web! Your efforts help preserve gaming history for future generations.
@@ -0,0 +1,328 @@
+# Flashpoint Web
+
+<div align="center">
+
+**A modern web interface for the Flashpoint Archive**
+
+Browse and play 70,000+ preserved Flash games and animations directly in your browser.
+
+<!-- Tech Stack Badges -->
+<p>
+  <img src="https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node.js" />
+  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/React-61DAFB?style=for-the-badge&logo=react&logoColor=black" alt="React" />
+  <img src="https://img.shields.io/badge/Express-000000?style=for-the-badge&logo=express&logoColor=white" alt="Express" />
+  <img src="https://img.shields.io/badge/Vite-646CFF?style=for-the-badge&logo=vite&logoColor=white" alt="Vite" />
+  <img src="https://img.shields.io/badge/Tailwind_CSS-06B6D4?style=for-the-badge&logo=tailwindcss&logoColor=white" alt="Tailwind CSS" />
+  <img src="https://img.shields.io/badge/SQLite-003B57?style=for-the-badge&logo=sqlite&logoColor=white" alt="SQLite" />
+  <img src="https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker" />
+</p>
+
+<!-- Project Badges -->
+<p>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-GPL--3.0-blue?style=flat-square" alt="License" /></a>
+  <img src="https://img.shields.io/badge/Node.js-20%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js 20+" />
+  <img src="https://img.shields.io/badge/PRs-Welcome-brightgreen?style=flat-square" alt="PRs Welcome" />
+</p>
+
+[Features](#key-features) | [Quick Start](#quick-start) | [Docker](#docker-deployment) | [Documentation](#documentation) | [Contributing](#contributing)
+
+</div>
+
+---
+
+## What is Flashpoint Web?
+
+Flashpoint Web is a self-hosted web application for accessing your local [Flashpoint Archive](https://flashpointarchive.org/) 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 70,000+ games with advanced filtering by platform, developer, tags, and more
+- **Play in Browser** - Flash games via [Ruffle](https://ruffle.rs/) 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](https://nodejs.org/) 20+ and npm 9+
+- [Flashpoint Archive](https://flashpointarchive.org/) installed locally
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-username/flashpoint-web.git
+cd flashpoint-web
+
+# Install dependencies for all services
+npm run install:all
+```
+
+### Configuration
+
+**1. Backend** (`backend/.env`)
+
+```bash
+cp backend/.env.example backend/.env
+```
+
+Edit `backend/.env`:
+
+```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`)
+
+```bash
+cp game-service/.env.example game-service/.env
+```
+
+```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
+
+```bash
+# 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:
+
+```bash
+# 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](docs/09-deployment/docker-deployment.md) 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](docs/08-development/commands.md) for the complete list.
+
+## Documentation
+
+Comprehensive documentation is available in the [`docs/`](docs/) directory:
+
+### Getting Started
+- [Project Overview](docs/01-overview/project-overview.md) - What is Flashpoint Web
+- [Setup Guide](docs/08-development/setup-guide.md) - Complete development setup
+- [Commands Reference](docs/08-development/commands.md) - All available commands
+
+### Architecture
+- [System Architecture](docs/02-architecture/system-architecture.md) - Service design overview
+- [Authentication Flow](docs/02-architecture/authentication-flow.md) - JWT-based auth system
+- [Game Launch Flow](docs/02-architecture/game-launch-flow.md) - How games are served
+
+### Services
+- [Backend](docs/03-backend/README.md) - REST API documentation
+- [Frontend](docs/04-frontend/README.md) - React application guide
+- [Game Service](docs/05-game-service/README.md) - File serving architecture
+
+### API Reference
+- [Authentication API](docs/06-api-reference/authentication-api.md)
+- [Games API](docs/06-api-reference/games-api.md)
+- [Playlists API](docs/06-api-reference/playlists-api.md)
+- [Full API Reference](docs/06-api-reference/README.md)
+
+### Deployment
+- [Docker Deployment](docs/09-deployment/docker-deployment.md)
+- [Production Setup](docs/09-deployment/production-setup.md)
+- [Environment Variables](docs/08-development/setup-guide.md#environment-variables-reference)
+
+### Features
+- [Authentication & Authorization](docs/10-features/01-authentication-authorization.md)
+- [Game Browsing & Filtering](docs/10-features/02-game-browsing-filtering.md)
+- [Play Session Tracking](docs/10-features/04-play-session-tracking.md)
+- [All Features](docs/10-features/README.md)
+
+## Technology Stack
+
+<table>
+<tr>
+<td align="center" width="33%">
+
+### Backend
+<p>
+  <img src="https://img.shields.io/badge/Node.js-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js" />
+  <img src="https://img.shields.io/badge/Express-000000?style=flat-square&logo=express&logoColor=white" alt="Express" />
+  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" />
+</p>
+
+- Express 4.18
+- BetterSqlite3 12.6
+- JWT + bcrypt
+- Winston logging
+- Zod validation
+
+</td>
+<td align="center" width="33%">
+
+### Frontend
+<p>
+  <img src="https://img.shields.io/badge/React-61DAFB?style=flat-square&logo=react&logoColor=black" alt="React" />
+  <img src="https://img.shields.io/badge/Vite-646CFF?style=flat-square&logo=vite&logoColor=white" alt="Vite" />
+  <img src="https://img.shields.io/badge/Tailwind-06B6D4?style=flat-square&logo=tailwindcss&logoColor=white" alt="Tailwind" />
+</p>
+
+- React 18.3 + TypeScript
+- TanStack Query 5.28
+- Zustand 4.5
+- Shadcn UI + Radix
+- Ruffle Flash Emulator
+
+</td>
+<td align="center" width="33%">
+
+### Game Service
+<p>
+  <img src="https://img.shields.io/badge/Node.js-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js" />
+  <img src="https://img.shields.io/badge/Express-000000?style=flat-square&logo=express&logoColor=white" alt="Express" />
+</p>
+
+- Express 4.18
+- node-stream-zip 1.15
+- Winston logging
+- CDN fallback support
+
+</td>
+</tr>
+</table>
+
+See [Technology Stack](docs/01-overview/technology-stack.md) for detailed explanations of each choice.
+
+## Troubleshooting
+
+### Common Issues
+
+**Port already in use:**
+```bash
+# 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:**
+```bash
+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](docs/08-development/common-pitfalls.md) 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](CONTRIBUTING.md#commit-guidelines)
+5. **Push** to the branch: `git push origin feature/amazing-feature`
+6. **Open** a Pull Request
+
+Please read our [Contributing Guide](CONTRIBUTING.md) for detailed instructions, coding standards, and development setup.
+
+## Related Projects
+
+- [Flashpoint Archive](https://flashpointarchive.org/) - The game preservation project
+- [Flashpoint Launcher](https://github.com/FlashpointProject/launcher) - Official desktop launcher
+- [Ruffle](https://ruffle.rs/) - Flash Player emulator
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](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
+
+---
+
+<div align="center">
+
+**[Documentation](docs/)** | **[Report Bug](https://github.com/your-username/flashpoint-web/issues)** | **[Request Feature](https://github.com/your-username/flashpoint-web/issues)**
+
+</div>
@@ -173,43 +173,19 @@ cp .env.example .env

 #### Configure Required Variables

-Edit the `.env` file and update these critical paths:
+Edit the `.env` file and update these critical settings:

 ```bash
 # =============================================================================
-# CRITICAL: Update these paths to match your Flashpoint installation
+# CRITICAL: Only FLASHPOINT_PATH needs to be set
+# All other paths are derived automatically!
 # =============================================================================

 # Base path to your Flashpoint installation
 FLASHPOINT_PATH=D:/Flashpoint

-# Database path (should be inside Flashpoint installation)
-FLASHPOINT_DB_PATH=D:/Flashpoint/Data/flashpoint.sqlite
-
-# Legacy web content directory
-FLASHPOINT_HTDOCS_PATH=D:/Flashpoint/Legacy/htdocs
-
-# Images directory
-FLASHPOINT_IMAGES_PATH=D:/Flashpoint/Data/Images
-
-# Logos directory
-FLASHPOINT_LOGOS_PATH=D:/Flashpoint/Data/Logos
-
-# Playlists directory
-FLASHPOINT_PLAYLISTS_PATH=D:/Flashpoint/Data/Playlists
-
-# Game data directory (ZIP files)
-FLASHPOINT_GAMES_PATH=D:/Flashpoint/Data/Games
-
-# =============================================================================
-# Service URLs (use defaults for local development)
-# =============================================================================
-
-# Game service proxy URL
-GAME_SERVICE_PROXY_URL=http://localhost:22500
-
-# Game service GameZip URL
-GAME_SERVICE_GAMEZIP_URL=http://localhost:22501
+# Game service host (use localhost for development)
+GAME_SERVICE_HOST=localhost

 # Frontend origin for CORS
 DOMAIN=http://localhost:5173
@@ -240,6 +216,18 @@ RATE_LIMIT_MAX_REQUESTS=100
 - **Linux/macOS**: Use absolute paths
  - Example: `/home/username/Flashpoint` or `/Users/username/Flashpoint`

+**Path Derivation**:
+
+All other paths are automatically derived from `FLASHPOINT_PATH`:
+- Database: `${FLASHPOINT_PATH}/Data/flashpoint.sqlite`
+- HTDOCS: `${FLASHPOINT_PATH}/Legacy/htdocs`
+- Images: `${FLASHPOINT_PATH}/Data/Images`
+- Logos: `${FLASHPOINT_PATH}/Data/Logos`
+- Playlists: `${FLASHPOINT_PATH}/Data/Playlists`
+- Games: `${FLASHPOINT_PATH}/Data/Games`
+
+You do not need to set individual path environment variables.
+
 ### Step 4: Configure Game Service Environment

 The game service also needs to know where Flashpoint is installed.
@@ -257,10 +245,8 @@ cp .env.example .env
 Update these variables in `game-service/.env`:

 ```bash
-# Flashpoint paths
+# Flashpoint path (HTDOCS and Games paths are derived automatically)
 FLASHPOINT_PATH=D:/Flashpoint
-FLASHPOINT_HTDOCS_PATH=D:/Flashpoint/Legacy/htdocs
-FLASHPOINT_GAMES_PATH=D:/Flashpoint/Data/Games

 # Server ports (defaults should work)
 PROXY_PORT=22500
@@ -273,19 +259,11 @@ EXTERNAL_FALLBACK_URLS=http://infinity.flashpointarchive.org/Flashpoint/Legacy/h
 LOG_LEVEL=info
 ```

-### Step 5: Configure Frontend Environment (Optional)
+### Step 5: Frontend Configuration (No Environment Variables Needed)

-The frontend has minimal configuration and works with defaults for development.
+The frontend does not require any environment variable configuration. The Vite development server uses a proxy configuration in `vite.config.ts` to automatically route API requests to the backend at `http://localhost:3100`.

-```bash
-# Navigate to frontend directory
-cd ../frontend
-
-# Create .env file (optional - defaults work for development)
-echo "VITE_API_URL=http://localhost:3100" > .env
-```
-
-The Vite development server uses a proxy configuration in `vite.config.ts`, so this is optional.
+No `.env` file is needed for the frontend in development or production.

 ### Step 6: Verify Configuration

@@ -535,8 +513,8 @@ GAMEZIPSERVER_PORT=22503

 **Solution**:
 1. Verify game service is running on ports 22500 and 22501
-2. Check paths in `game-service/.env`
-3. Verify `FLASHPOINT_HTDOCS_PATH` and `FLASHPOINT_GAMES_PATH` are correct
+2. Check `FLASHPOINT_PATH` in `game-service/.env` (paths are derived automatically)
+3. Verify FLASHPOINT_PATH points to correct Flashpoint installation

 ### Issue: SQLite "database is locked" error

@@ -43,6 +43,9 @@ Flashpoint Web is built with modern, production-ready technologies chosen for th
 | node-stream-zip | 1.15 | ZIP archive streaming |
 | Axios | 1.6 | HTTP client for CDN |
 | Winston | 3.11 | Logging |
+| Zod | 4.3 | Schema validation |
+
+> **Note:** Game Service uses TypeScript 5.3 while Backend/Frontend use 5.4. This is intentional and both versions are compatible.

 ### Development Tools

@@ -101,9 +101,8 @@ npm start
 See [configuration.md](./configuration.md) for complete environment variable documentation.

 Required variables:
- `FLASHPOINT_PATH` - Path to Flashpoint installation
- `FLASHPOINT_DB_PATH` - Path to flashpoint.sqlite
- `GAME_SERVICE_PROXY_URL` - URL to game-service proxy (default: http://localhost:22500)
+- `FLASHPOINT_PATH` - Path to Flashpoint installation (all other paths are derived automatically)
+- `GAME_SERVICE_HOST` - Game service hostname/IP (default: localhost)
 - `DOMAIN` - Frontend URL (default: http://localhost:5173)

 ## Core Concepts
@@ -294,8 +293,8 @@ npm test -- --coverage

 ### Game Files Not Loading
 - Verify game-service is running on port 22500/22501
- Check GAME_SERVICE_PROXY_URL in .env
- Ensure Flashpoint paths are correct
+- Check GAME_SERVICE_HOST in .env (default: localhost)
+- Ensure FLASHPOINT_PATH is correct

 ## Related Documentation

@@ -17,9 +17,20 @@ export const config = {
  port: parseInt(process.env.PORT || '3100', 10),
  host: process.env.HOST || '0.0.0.0',

-  // Flashpoint paths
+  // Flashpoint paths (only FLASHPOINT_PATH is needed)
  flashpointPath: process.env.FLASHPOINT_PATH || 'D:/Flashpoint',
-  flashpointDbPath: process.env.FLASHPOINT_DB_PATH || 'D:/Flashpoint/Data/flashpoint.sqlite',
+  // All other paths are derived automatically:
+  // - flashpointDbPath: ${flashpointPath}/Data/flashpoint.sqlite
+  // - htdocsPath: ${flashpointPath}/Legacy/htdocs
+  // - imagesPath: ${flashpointPath}/Data/Images
+  // - logosPath: ${flashpointPath}/Data/Logos
+  // - playlistsPath: ${flashpointPath}/Data/Playlists
+  // - gamesPath: ${flashpointPath}/Data/Games
+
+  // Game service host (proxy and gamezip URLs derived automatically)
+  gameServiceHost: process.env.GAME_SERVICE_HOST || 'localhost',
+  // - proxyUrl: http://${gameServiceHost}:22500
+  // - gamezipUrl: http://${gameServiceHost}:22501
  // ... more config
 };
 ```
@@ -70,87 +81,35 @@ export const config = {
  FLASHPOINT_PATH=/mnt/flashpoint  # Linux
  ```

-#### `FLASHPOINT_DB_PATH`
- **Type**: string
- **Default**: `D:/Flashpoint/Data/flashpoint.sqlite`
- **Required**: Yes
- **Description**: Path to Flashpoint game metadata database
- **Usage**:
-  ```bash
-  FLASHPOINT_DB_PATH=D:/Flashpoint/Data/flashpoint.sqlite
-  ```
+**Automatically Derived Paths (no configuration needed):**

-#### `FLASHPOINT_HTDOCS_PATH`
- **Type**: string
- **Default**: `D:/Flashpoint/Legacy/htdocs`
- **Description**: Path to legacy web content directory
- **Usage**:
-  ```bash
-  FLASHPOINT_HTDOCS_PATH=D:/Flashpoint/Legacy/htdocs
-  ```
+All other Flashpoint paths are automatically derived from `FLASHPOINT_PATH`:

-#### `FLASHPOINT_IMAGES_PATH`
- **Type**: string
- **Default**: `D:/Flashpoint/Data/Images`
- **Description**: Path to game screenshots directory
- **Usage**:
-  ```bash
-  FLASHPOINT_IMAGES_PATH=D:/Flashpoint/Data/Images
-  ```
+- Database: `${FLASHPOINT_PATH}/Data/flashpoint.sqlite`
+- HTDOCS: `${FLASHPOINT_PATH}/Legacy/htdocs`
+- Images: `${FLASHPOINT_PATH}/Data/Images`
+- Logos: `${FLASHPOINT_PATH}/Data/Logos`
+- Playlists: `${FLASHPOINT_PATH}/Data/Playlists`
+- Games: `${FLASHPOINT_PATH}/Data/Games`

-#### `FLASHPOINT_LOGOS_PATH`
- **Type**: string
- **Default**: `D:/Flashpoint/Data/Logos`
- **Description**: Path to game logos/box art directory
- **Usage**:
-  ```bash
-  FLASHPOINT_LOGOS_PATH=D:/Flashpoint/Data/Logos
-  ```
-
-#### `FLASHPOINT_PLAYLISTS_PATH`
- **Type**: string
- **Default**: `D:/Flashpoint/Data/Playlists`
- **Description**: Path to playlist files directory
- **Usage**:
-  ```bash
-  FLASHPOINT_PLAYLISTS_PATH=D:/Flashpoint/Data/Playlists
-  ```
-
-#### `FLASHPOINT_GAMES_PATH`
- **Type**: string
- **Default**: `D:/Flashpoint/Data/Games`
- **Description**: Path to game data/ZIP files directory
- **Usage**:
-  ```bash
-  FLASHPOINT_GAMES_PATH=D:/Flashpoint/Data/Games
-  ```
+You do not need to set environment variables for these paths - they are calculated automatically from `FLASHPOINT_PATH`.

 ### Game Service Configuration

-#### `GAME_SERVICE_PROXY_URL`
+#### `GAME_SERVICE_HOST`
 - **Type**: string
- **Default**: `http://localhost:22500`
- **Description**: URL to game-service HTTP proxy server
+- **Default**: `localhost`
+- **Description**: Hostname/IP of game-service for constructing proxy and GameZip URLs
 - **Usage**:
  ```bash
-  GAME_SERVICE_PROXY_URL=http://localhost:22500
-  GAME_SERVICE_PROXY_URL=http://game-service:22500  # Docker
+  GAME_SERVICE_HOST=localhost  # Development
+  GAME_SERVICE_HOST=game-service  # Docker
+  GAME_SERVICE_HOST=192.168.1.100  # Remote
  ```

-#### `GAME_SERVICE_GAMEZIP_URL`
- **Type**: string
- **Default**: `http://localhost:22501`
- **Description**: URL to game-service GameZip server
- **Usage**:
-  ```bash
-  GAME_SERVICE_GAMEZIP_URL=http://localhost:22501
-  ```
-
-#### `GAME_SERVER_URL` (Legacy)
- **Type**: string
- **Default**: `http://localhost:22500`
- **Description**: Legacy alias for `GAME_SERVICE_PROXY_URL`
- **Note**: Deprecated, use `GAME_SERVICE_PROXY_URL` instead
+The proxy and GameZip server URLs are automatically constructed as:
+- Proxy: `http://${GAME_SERVICE_HOST}:22500`
+- GameZip: `http://${GAME_SERVICE_HOST}:22501`

 ### External Resources

@@ -326,17 +285,11 @@ PORT=3100
 HOST=0.0.0.0

 # Flashpoint (Windows)
+# All other paths are derived automatically from FLASHPOINT_PATH
 FLASHPOINT_PATH=D:/Flashpoint
-FLASHPOINT_DB_PATH=D:/Flashpoint/Data/flashpoint.sqlite
-FLASHPOINT_HTDOCS_PATH=D:/Flashpoint/Legacy/htdocs
-FLASHPOINT_IMAGES_PATH=D:/Flashpoint/Data/Images
-FLASHPOINT_LOGOS_PATH=D:/Flashpoint/Data/Logos
-FLASHPOINT_PLAYLISTS_PATH=D:/Flashpoint/Data/Playlists
-FLASHPOINT_GAMES_PATH=D:/Flashpoint/Data/Games

 # Game Service
-GAME_SERVICE_PROXY_URL=http://localhost:22500
-GAME_SERVICE_GAMEZIP_URL=http://localhost:22501
+GAME_SERVICE_HOST=localhost

 # Database
 USER_DB_PATH=./user.db
@@ -363,17 +316,11 @@ PORT=3100
 HOST=0.0.0.0

 # Flashpoint (Linux)
+# All other paths are derived automatically from FLASHPOINT_PATH
 FLASHPOINT_PATH=/mnt/flashpoint
-FLASHPOINT_DB_PATH=/mnt/flashpoint/Data/flashpoint.sqlite
-FLASHPOINT_HTDOCS_PATH=/mnt/flashpoint/Legacy/htdocs
-FLASHPOINT_IMAGES_PATH=/mnt/flashpoint/Data/Images
-FLASHPOINT_LOGOS_PATH=/mnt/flashpoint/Data/Logos
-FLASHPOINT_PLAYLISTS_PATH=/mnt/flashpoint/Data/Playlists
-FLASHPOINT_GAMES_PATH=/mnt/flashpoint/Data/Games

 # Game Service
-GAME_SERVICE_PROXY_URL=http://game-service:22500
-GAME_SERVICE_GAMEZIP_URL=http://game-service:22501
+GAME_SERVICE_HOST=game-service

 # Database
 USER_DB_PATH=/data/user.db
@@ -409,17 +356,11 @@ PORT=3100
 HOST=0.0.0.0

 # Flashpoint (mounted volume)
+# All other paths are derived automatically from FLASHPOINT_PATH
 FLASHPOINT_PATH=/flashpoint
-FLASHPOINT_DB_PATH=/flashpoint/Data/flashpoint.sqlite
-FLASHPOINT_HTDOCS_PATH=/flashpoint/Legacy/htdocs
-FLASHPOINT_IMAGES_PATH=/flashpoint/Data/Images
-FLASHPOINT_LOGOS_PATH=/flashpoint/Data/Logos
-FLASHPOINT_PLAYLISTS_PATH=/flashpoint/Data/Playlists
-FLASHPOINT_GAMES_PATH=/flashpoint/Data/Games

 # Game Service (Docker network)
-GAME_SERVICE_PROXY_URL=http://game-service:22500
-GAME_SERVICE_GAMEZIP_URL=http://game-service:22501
+GAME_SERVICE_HOST=game-service

 # Database (Docker volume)
 USER_DB_PATH=/data/user.db
@@ -508,7 +449,8 @@ if (!fs.existsSync(config.flashpointDbPath)) {
 **Database not found**:
 ```
 Error: Flashpoint database not found at: D:/Flashpoint/Data/flashpoint.sqlite
-Solution: Verify FLASHPOINT_DB_PATH points to valid database file
+Solution: Verify FLASHPOINT_PATH environment variable points to valid Flashpoint installation
+(Database path is derived automatically as ${FLASHPOINT_PATH}/Data/flashpoint.sqlite)
 ```

 **Port already in use**:
@@ -87,33 +87,14 @@ FLASHPOINT_PATH=/Applications/Flashpoint
 FLASHPOINT_PATH=/Users/user/flashpoint
 ```

-#### FLASHPOINT_HTDOCS_PATH
+**Automatically Derived Paths (no configuration needed):**

-Legacy htdocs directory path.
+All other Flashpoint paths are automatically derived from `FLASHPOINT_PATH`:

-```bash
-FLASHPOINT_HTDOCS_PATH=D:/Flashpoint/Legacy/htdocs
-```
+- HTDOCS: `${FLASHPOINT_PATH}/Legacy/htdocs`
+- Games: `${FLASHPOINT_PATH}/Data/Games`

-**Default**: `${FLASHPOINT_PATH}/Legacy/htdocs`
-**Type**: Absolute path
-**Required**: No (derived from FLASHPOINT_PATH)
-
-**Use case**: Override htdocs location
-
-#### FLASHPOINT_GAMES_PATH
-
-Game ZIP archives directory.
-
-```bash
-FLASHPOINT_GAMES_PATH=D:/Flashpoint/Data/Games
-```
-
-**Default**: `${FLASHPOINT_PATH}/Data/Games`
-**Type**: Absolute path
-**Required**: No (derived from FLASHPOINT_PATH)
-
-**Use case**: Override games directory location
+You do not need to set environment variables for these paths - they are calculated automatically from `FLASHPOINT_PATH`.

 ### Proxy Settings

@@ -487,11 +468,12 @@ export class ConfigManager {
 const proxySettingsPath = path.join(flashpointPath, 'Server', 'proxySettings.json');
 const proxySettings = JSON.parse(await fs.readFile(proxySettingsPath, 'utf-8'));

-// 2. Override with environment variables
+// 2. Derive paths automatically from FLASHPOINT_PATH
 this.settings = {
  proxyPort: parseInt(process.env.PROXY_PORT || '22500'),
-  legacyHTDOCSPath: process.env.FLASHPOINT_HTDOCS_PATH ||
-                    path.join(flashpointPath, 'Legacy', 'htdocs'),
+  // All paths are derived automatically from flashpointPath:
+  legacyHTDOCSPath: path.join(flashpointPath, 'Legacy', 'htdocs'),
+  gamesPath: path.join(flashpointPath, 'Data', 'Games'),
  // ... etc
 };
 ```
@@ -516,7 +498,7 @@ console.log(`Proxy port: ${settings.proxyPort}`);
 Settings that MUST be configured:

 1. **FLASHPOINT_PATH**: Must point to valid Flashpoint installation
-2. **FLASHPOINT_HTDOCS_PATH**: Must exist and be readable
+   - All other paths (HTDOCS, GAMES) are derived automatically from this

 ### Validation Process

@@ -678,19 +678,14 @@ Create `.vscode/tasks.json`:
 ### Required for Commands

 **Backend:**
- `FLASHPOINT_PATH`: Path to Flashpoint installation
- `FLASHPOINT_DB_PATH`: Path to flashpoint.sqlite
- `FLASHPOINT_HTDOCS_PATH`: Path to htdocs folder
- `GAME_SERVICE_PROXY_URL`: Game service proxy URL
- `GAME_SERVICE_GAMEZIP_URL`: Game service GameZip URL
+- `FLASHPOINT_PATH`: Path to Flashpoint installation (all other paths derived automatically)
+- `GAME_SERVICE_HOST`: Game service hostname/IP (default: localhost)

 **Game Service:**
- `FLASHPOINT_PATH`: Path to Flashpoint installation
- `FLASHPOINT_HTDOCS_PATH`: Path to htdocs folder
- `FLASHPOINT_GAMES_PATH`: Path to Games folder
+- `FLASHPOINT_PATH`: Path to Flashpoint installation (all other paths derived automatically)

 **Frontend:**
- `VITE_API_URL`: Backend API URL (build time)
+- No environment variables required (proxies through backend via Vite in development, Nginx in production)

 See [Configuration Documentation](../03-backend/configuration.md) for complete details.

@@ -43,13 +43,15 @@ cp .env.example .env
 # 3. Edit .env with correct paths
 # Windows paths use forward slashes or escaped backslashes
 FLASHPOINT_PATH=D:/Flashpoint
-FLASHPOINT_DB_PATH=D:/Flashpoint/Data/flashpoint.sqlite
+JWT_SECRET=your-secure-secret

 # Alternative Windows format
 FLASHPOINT_PATH=D:\\Flashpoint
-FLASHPOINT_DB_PATH=D:\\Flashpoint\\Data\\flashpoint.sqlite

-# 4. Verify paths in .env match actual installation
+# Note: All other paths (database, images, logos, etc.) are
+# automatically derived from FLASHPOINT_PATH
+
+# 4. Verify FLASHPOINT_PATH points to valid Flashpoint installation
 ```

 **Prevention:**
@@ -486,8 +488,8 @@ ls -l D:/Flashpoint/Legacy/htdocs/

 # 6. Verify backend proxy configuration
 # backend/.env
-GAME_SERVICE_PROXY_URL=http://localhost:22500
-GAME_SERVICE_GAMEZIP_URL=http://localhost:22501
+GAME_SERVICE_HOST=localhost
+# (proxy and gamezip URLs are derived automatically as http://localhost:22500 and :22501)
 ```

 **Prevention:**
@@ -137,65 +137,58 @@ cp .env.example .env
 **2. Edit `.env` file:**

 ```bash
-# Windows paths (use forward slashes or escaped backslashes)
+# Required
 FLASHPOINT_PATH=D:/Flashpoint
-FLASHPOINT_DB_PATH=D:/Flashpoint/Data/flashpoint.sqlite
-FLASHPOINT_HTDOCS_PATH=D:/Flashpoint/Legacy/htdocs
-FLASHPOINT_IMAGES_PATH=D:/Flashpoint/Data/Images
-FLASHPOINT_LOGOS_PATH=D:/Flashpoint/Data/Logos
-FLASHPOINT_PLAYLISTS_PATH=D:/Flashpoint/Data/Playlists
-FLASHPOINT_GAMES_PATH=D:/Flashpoint/Data/Games
+JWT_SECRET=your-secret-key-change-in-production

-# Linux/Mac paths
-# FLASHPOINT_PATH=/home/user/Flashpoint
-# FLASHPOINT_DB_PATH=/home/user/Flashpoint/Data/flashpoint.sqlite
-# ... etc
-
-# Game service URLs
-GAME_SERVICE_PROXY_URL=http://localhost:22500
-GAME_SERVICE_GAMEZIP_URL=http://localhost:22501
-
-# Server configuration
-PORT=3100
+# Optional settings
+NODE_ENV=development
+LOG_LEVEL=info
 DOMAIN=http://localhost:5173

-# JWT secret (change in production!)
-JWT_SECRET=your-secret-key-change-in-production
-JWT_EXPIRES_IN=7d
-JWT_REFRESH_EXPIRES_IN=30d
+# Backend -> game-service connection (local development)
+GAME_SERVICE_HOST=localhost

-# Logging
-LOG_LEVEL=info
+# Rate limiting
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX_REQUESTS=100
+
+# Auth
+JWT_EXPIRES_IN=1h
+BCRYPT_SALT_ROUNDS=10
+
+# Redis (optional)
+REDIS_ENABLED=false
+REDIS_HOST=localhost
+REDIS_PORT=6379
+
+# Database optimization (for network storage)
+ENABLE_LOCAL_DB_COPY=false
+SQLITE_CACHE_SIZE=-64000
+SQLITE_MMAP_SIZE=268435456
+ENABLE_CACHE_PREWARM=true
 ```

+> **Note:** All paths (database, images, logos, htdocs, games) are automatically derived from `FLASHPOINT_PATH`. You only need to set the base path.
+
 **3. Verify paths:**

 ```bash
-# Test that paths are accessible
-ls $FLASHPOINT_DB_PATH
+# Test that Flashpoint path is accessible
+ls $FLASHPOINT_PATH/Data/flashpoint.sqlite

 # Windows CMD
-dir %FLASHPOINT_DB_PATH%
+dir %FLASHPOINT_PATH%\Data\flashpoint.sqlite

 # Windows PowerShell
-Test-Path $env:FLASHPOINT_DB_PATH
+Test-Path "$env:FLASHPOINT_PATH\Data\flashpoint.sqlite"
 ```

 ### Frontend Configuration

-**1. Create environment file:**
+The frontend does not require a `.env` file for local development. API calls are automatically proxied through Vite to the backend.

-```bash
-cd frontend
-cp .env.example .env
-```
-
-**2. Edit `.env` file:**
-
-```bash
-# Backend API URL
-VITE_API_URL=http://localhost:3100
-```
+> **Note:** In production (Docker), the frontend uses Nginx to proxy API requests to the backend container.

 ### Game Service Configuration

@@ -209,20 +202,21 @@ cp .env.example .env
 **2. Edit `.env` file:**

 ```bash
-# Server ports
-PROXY_PORT=22500
-GAMEZIPSERVER_PORT=22501
-
-# Flashpoint paths (must match backend)
+# Flashpoint Installation Path (required)
+# All other paths are automatically derived from this
 FLASHPOINT_PATH=D:/Flashpoint
-FLASHPOINT_HTDOCS_PATH=D:/Flashpoint/Legacy/htdocs
-FLASHPOINT_GAMES_PATH=D:/Flashpoint/Data/Games
-
-# External fallback CDNs
-EXTERNAL_FALLBACK_URLS=http://infinity.flashpointarchive.org/Flashpoint/Legacy/htdocs,http://infinity.unstable.life/Flashpoint/Legacy/htdocs/

 # Logging
 LOG_LEVEL=info
+NODE_ENV=development
+
+# External Fallback URLs (comma-separated)
+# Used when files are not found locally
+EXTERNAL_FALLBACK_URLS=http://infinity.flashpointarchive.org/Flashpoint/Legacy/htdocs,http://infinity.unstable.life/Flashpoint/Legacy/htdocs/
+
+# CGI and Advanced Features (optional)
+ENABLE_CGI=false
+ENABLE_HTACCESS=false
 ```

 ---
@@ -471,9 +465,9 @@ npm run kill-port
 ls D:/Flashpoint/Data/flashpoint.sqlite

 # Check .env file
-cat backend/.env | grep FLASHPOINT_DB_PATH
+cat backend/.env | grep FLASHPOINT_PATH

-# Ensure path matches
+# Ensure path matches (db and other paths are derived automatically from FLASHPOINT_PATH)
 ```

 **Issue: Dependencies Won't Install**
@@ -589,38 +583,46 @@ Use this checklist to verify your setup:

 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `FLASHPOINT_PATH` | Yes | - | Path to Flashpoint installation |
-| `FLASHPOINT_DB_PATH` | Yes | - | Path to flashpoint.sqlite |
-| `FLASHPOINT_HTDOCS_PATH` | Yes | - | Path to htdocs folder |
-| `FLASHPOINT_IMAGES_PATH` | Yes | - | Path to Images folder |
-| `FLASHPOINT_LOGOS_PATH` | Yes | - | Path to Logos folder |
-| `FLASHPOINT_PLAYLISTS_PATH` | Yes | - | Path to Playlists folder |
-| `FLASHPOINT_GAMES_PATH` | Yes | - | Path to Games folder |
-| `GAME_SERVICE_PROXY_URL` | Yes | - | Game service proxy URL |
-| `GAME_SERVICE_GAMEZIP_URL` | Yes | - | Game service GameZip URL |
-| `PORT` | No | 3100 | Backend server port |
-| `DOMAIN` | Yes | - | Frontend URL for CORS |
-| `JWT_SECRET` | No | auto | JWT signing secret |
-| `JWT_EXPIRES_IN` | No | 7d | JWT expiration |
-| `LOG_LEVEL` | No | info | Logging level |
+| `FLASHPOINT_PATH` | Yes | - | Path to Flashpoint installation (all other paths derived from this) |
+| `JWT_SECRET` | Yes* | auto-generated | JWT signing secret (*required in production) |
+| `NODE_ENV` | No | development | Environment mode |
+| `DOMAIN` | No | http://localhost:5173 | Frontend URL for CORS |
+| `GAME_SERVICE_HOST` | No | localhost | Hostname of game service |
+| `LOG_LEVEL` | No | info | Logging level (error, warn, info, debug) |
+| `JWT_EXPIRES_IN` | No | 1h | JWT access token expiration |
+| `BCRYPT_SALT_ROUNDS` | No | 10 | Password hashing rounds |
+| `RATE_LIMIT_WINDOW_MS` | No | 60000 | Rate limit window in milliseconds |
+| `RATE_LIMIT_MAX_REQUESTS` | No | 100 | Max requests per window |
+| `REDIS_ENABLED` | No | false | Enable Redis caching |
+| `REDIS_HOST` | No | localhost | Redis server hostname |
+| `REDIS_PORT` | No | 6379 | Redis server port |
+| `ENABLE_LOCAL_DB_COPY` | No | false | Copy flashpoint.sqlite locally (for network storage) |
+| `SQLITE_CACHE_SIZE` | No | -64000 | SQLite cache size (negative = KB) |
+| `SQLITE_MMAP_SIZE` | No | 268435456 | SQLite memory-mapped I/O size |
+| `ENABLE_CACHE_PREWARM` | No | true | Pre-warm caches on startup |

-### Frontend (.env)
+### Frontend
+
+The frontend does not require environment variables for local development. API calls are proxied through Vite.
+
+For production builds, you can optionally set:

 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `VITE_API_URL` | Yes | - | Backend API URL |
+| `VITE_APP_VERSION` | No | 1.0.0 | Displayed app version |

 ### Game Service (.env)

 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `PROXY_PORT` | No | 22500 | Proxy server port |
-| `GAMEZIPSERVER_PORT` | No | 22501 | GameZip server port |
 | `FLASHPOINT_PATH` | Yes | - | Path to Flashpoint installation |
-| `FLASHPOINT_HTDOCS_PATH` | Yes | - | Path to htdocs folder |
-| `FLASHPOINT_GAMES_PATH` | Yes | - | Path to Games folder |
-| `EXTERNAL_FALLBACK_URLS` | No | - | Comma-separated CDN URLs |
+| `NODE_ENV` | No | development | Environment mode |
+| `PROXY_PORT` | No | 22500 | HTTP proxy server port |
+| `GAMEZIPSERVER_PORT` | No | 22501 | GameZip server port |
+| `EXTERNAL_FALLBACK_URLS` | No | - | Comma-separated CDN URLs for fallback |
 | `LOG_LEVEL` | No | info | Logging level |
+| `ENABLE_CGI` | No | false | Enable CGI support |
+| `ENABLE_HTACCESS` | No | false | Enable .htaccess support |

 ---

@@ -232,7 +232,7 @@ Each service uses a production-optimized Dockerfile with multi-stage builds for
 | Service | Build Args | Default |
 |---------|-----------|---------|
 | Backend | None | - |
-| Frontend | `VITE_API_URL` | `http://localhost:3100` |
+| Frontend | None | Frontend proxies to backend via Nginx, no build-time API configuration needed |
 | Game Service | None | - |

 **Note:** For development, use `npm run dev` locally outside of Docker for faster iteration.
@@ -244,8 +244,8 @@ Each service uses a production-optimized Dockerfile with multi-stage builds for
 # Backend
 docker build -t flashpoint-backend:latest backend/

-# Frontend (with API URL)
-docker build --build-arg VITE_API_URL=http://localhost:3100 -t flashpoint-frontend:latest frontend/
+# Frontend (no build-time API URL configuration needed)
+docker build -t flashpoint-frontend:latest frontend/

 # Game Service
 docker build -t flashpoint-game-service:latest game-service/
@@ -540,15 +540,14 @@ docker system prune -a --volumes

 ### Custom Build Args

-Modify Dockerfiles with build arguments:
+Frontend no longer requires build-time API configuration. Backend and game-service can be customized via environment variables in docker-compose.override.yml if needed:

 ```yaml
 # docker-compose.override.yml
 services:
-  frontend:
-    build:
-      args:
-        - VITE_API_URL=https://api.example.com
+  backend:
+    environment:
+      - LOG_LEVEL=debug
 ```

 ### Multi-Host Deployment
@@ -253,11 +253,13 @@ networks:

 | Service | Internal Port | Host Port | Description |
 |---------|---------------|-----------|-------------|
-| Frontend | 80 | 80 | Web UI |
+| Frontend | 8080 | 80 | Web UI (Nginx) |
 | Backend | 3100 | 3100 | REST API |
 | Game Service (Proxy) | 22500 | 22500 | HTTP Proxy |
 | Game Service (ZIP) | 22501 | 22501 | GameZip Server |

+> **Note:** The frontend container runs Nginx on internal port 8080, which is mapped to host port 80 by default.
+
 **Custom Port Configuration:**

 Use environment variables to change host ports:
@@ -277,31 +279,45 @@ Each service includes health checks for container orchestration:

 ### Backend Health Check

-```dockerfile
-HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=40s \
-  CMD node -e "require('http').get('http://localhost:3100/health', (res) => { \
-    process.exit(res.statusCode === 200 ? 0 : 1); \
-  }).on('error', () => process.exit(1));"
+```yaml
+healthcheck:
+  test: ["CMD", "curl", "--fail", "http://localhost:3100/api/health"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+  start_period: 40s
+```
+
+**Endpoint:** `GET /api/health`
+**Expected Response:** `200 OK`
+
+### Game Service Health Check
+
+```yaml
+healthcheck:
+  test: ["CMD", "curl", "--fail", "http://localhost:22500/health"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+  start_period: 30s
 ```

 **Endpoint:** `GET /health`
 **Expected Response:** `200 OK`

-### Game Service Health Check
-
-```dockerfile
-HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=30s \
-  CMD node -e "require('http').get('http://localhost:22500/', (res) => { \
-    process.exit(res.statusCode < 500 ? 0 : 1); \
-  }).on('error', () => process.exit(1));"
-```
-
-**Endpoint:** `GET /`
-**Expected Response:** Any non-5xx status
-
 ### Frontend Health Check

-Nginx automatically serves 200 OK on root path.
+```yaml
+healthcheck:
+  test: ["CMD", "curl", "--fail", "http://localhost:8080/"]
+  interval: 30s
+  timeout: 3s
+  retries: 3
+  start_period: 10s
+```
+
+**Endpoint:** `GET /` (Nginx root)
+**Expected Response:** `200 OK`

 ### Check Health Status

@@ -341,14 +357,8 @@ services:
      - PORT=3100
      - HOST=0.0.0.0
      - FLASHPOINT_PATH=/data/flashpoint
-      - FLASHPOINT_DB_PATH=/data/flashpoint/Data/flashpoint.sqlite
-      - FLASHPOINT_HTDOCS_PATH=/data/flashpoint/Legacy/htdocs
-      - FLASHPOINT_IMAGES_PATH=/data/flashpoint/Data/Images
-      - FLASHPOINT_LOGOS_PATH=/data/flashpoint/Data/Logos
-      - FLASHPOINT_PLAYLISTS_PATH=/data/flashpoint/Data/Playlists
-      - FLASHPOINT_GAMES_PATH=/data/flashpoint/Data/Games
-      - GAME_SERVICE_PROXY_URL=http://game-service:22500
-      - GAME_SERVICE_GAMEZIP_URL=http://game-service:22501
+      # Note: FLASHPOINT_DB_PATH, FLASHPOINT_HTDOCS_PATH, etc. are derived automatically from FLASHPOINT_PATH
+      - GAME_SERVICE_HOST=game-service
      - JWT_SECRET=${JWT_SECRET}
      - DOMAIN=${DOMAIN:-http://localhost}
      - LOG_LEVEL=${LOG_LEVEL:-info}
@@ -392,11 +402,9 @@ services:
      - PROXY_PORT=22500
      - GAMEZIPSERVER_PORT=22501
      - FLASHPOINT_PATH=/data/flashpoint
-      - FLASHPOINT_HTDOCS_PATH=/data/flashpoint/Legacy/htdocs
-      - FLASHPOINT_GAMES_PATH=/data/flashpoint/Data/Games
+      # Note: FLASHPOINT_HTDOCS_PATH and FLASHPOINT_GAMES_PATH are derived automatically from FLASHPOINT_PATH
      - EXTERNAL_FALLBACK_URLS=${EXTERNAL_FALLBACK_URLS}
      - LOG_LEVEL=${LOG_LEVEL:-info}
-      - ALLOW_CROSS_DOMAIN=true
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:22500/', (res) => { process.exit(res.statusCode < 500 ? 0 : 1); }).on('error', () => process.exit(1));"]
      interval: 30s
@@ -417,8 +425,6 @@ services:
    build:
      context: ./frontend
      dockerfile: Dockerfile.prod
-      args:
-        - VITE_API_URL=${VITE_API_URL:-http://localhost:3100}
    image: flashpoint-frontend:latest
    container_name: flashpoint-frontend
    restart: unless-stopped
@@ -550,9 +556,7 @@ RUN npm ci
 # Copy source
 COPY . .

-# Build production bundle
-ARG VITE_API_URL
-ENV VITE_API_URL=${VITE_API_URL}
+# Build production bundle (no VITE_API_URL needed - frontend uses relative API paths)
 RUN npm run build

 # Production stage
@@ -54,7 +54,7 @@ HOST=127.0.0.1
 |----------|------|----------|-------------|
 | `FLASHPOINT_PATH` | string | Yes | Root directory of Flashpoint installation. All other paths are automatically derived from this. |

-**Automatically derived paths:**
+**Automatically derived paths (no environment variable needed):**
 - Database: `${FLASHPOINT_PATH}/Data/flashpoint.sqlite`
 - HTDOCS: `${FLASHPOINT_PATH}/Legacy/htdocs`
 - Images: `${FLASHPOINT_PATH}/Data/Images`
@@ -62,6 +62,8 @@ HOST=127.0.0.1
 - Playlists: `${FLASHPOINT_PATH}/Data/Playlists`
 - Games: `${FLASHPOINT_PATH}/Data/Games`

+All paths are derived automatically from `FLASHPOINT_PATH`. You only need to set `FLASHPOINT_PATH` - no need to set individual path variables.
+
 **Example (Windows):**

 ```bash
@@ -81,29 +83,30 @@ FLASHPOINT_PATH=/data/flashpoint
 FLASHPOINT_PATH=/data/flashpoint
 ```

-### Game Service URLs
+### Game Service Host

 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
-| `GAME_SERVICE_PROXY_URL` | string | `http://localhost:22500` | URL to game-service HTTP proxy |
-| `GAME_SERVICE_GAMEZIP_URL` | string | `http://localhost:22501` | URL to game-service GameZip server |
-| `GAME_SERVER_URL` | string | - | Legacy alias for `GAME_SERVICE_PROXY_URL` |
-| `GAME_SERVER_HTTP_PORT` | number | - | Legacy alias for GameZip port |
+| `GAME_SERVICE_HOST` | string | `localhost` | Hostname/IP of game-service for constructing URLs to proxy and GameZip servers |
+
+The proxy and GameZip URLs are automatically constructed as:
+- Proxy URL: `http://${GAME_SERVICE_HOST}:22500`
+- GameZip URL: `http://${GAME_SERVICE_HOST}:22501`

 **Examples:**

 ```bash
-# Local development
-GAME_SERVICE_PROXY_URL=http://localhost:22500
-GAME_SERVICE_GAMEZIP_URL=http://localhost:22501
+# Local development (default)
+GAME_SERVICE_HOST=localhost
+# Results in: http://localhost:22500 and http://localhost:22501

 # Docker (internal network)
-GAME_SERVICE_PROXY_URL=http://game-service:22500
-GAME_SERVICE_GAMEZIP_URL=http://game-service:22501
+GAME_SERVICE_HOST=game-service
+# Results in: http://game-service:22500 and http://game-service:22501

 # Remote game service
-GAME_SERVICE_PROXY_URL=http://192.168.1.100:22500
-GAME_SERVICE_GAMEZIP_URL=http://192.168.1.100:22501
+GAME_SERVICE_HOST=192.168.1.100
+# Results in: http://192.168.1.100:22500 and http://192.168.1.100:22501
 ```

 ### Image CDN URLs (Automatic)
@@ -426,45 +429,13 @@ LOG_ERRORS=true

 ## Frontend Environment Variables

-Location: `frontend/.env` (build time only)
+**The frontend does not require any environment variables in development or production.**

-### Build Configuration
+The API requests are proxied through the backend, either:
+- **Development**: Via Vite proxy configuration in `vite.config.ts` to `http://localhost:3100`
+- **Production**: Via Nginx reverse proxy or the same domain

-| Variable | Type | Default | Description |
-|----------|------|---------|-------------|
-| `VITE_API_URL` | string | `http://localhost:3100` | Backend API URL |
-
-**IMPORTANT:** Frontend environment variables are embedded at build time. Changes require rebuild.
-
-**Examples:**
-
-```bash
-# Development
-VITE_API_URL=http://localhost:3100
-
-# Production (same domain)
-VITE_API_URL=https://flashpoint.example.com
-
-# Production (API subdomain)
-VITE_API_URL=https://api.flashpoint.example.com
-
-# Production (different port)
-VITE_API_URL=https://flashpoint.example.com:8443
-```
-
-### Build with Custom API URL
-
-```bash
-# Option 1: Set in .env file
-echo "VITE_API_URL=https://api.example.com" > frontend/.env
-npm run build
-
-# Option 2: Inline environment variable
-VITE_API_URL=https://api.example.com npm run build
-
-# Option 3: Docker build arg
-docker build --build-arg VITE_API_URL=https://api.example.com -t frontend .
-```
+No `VITE_API_URL` configuration is needed. The frontend automatically uses the relative API paths `/api/*`.

 ## Docker Environment Variables

@@ -547,18 +518,11 @@ NODE_ENV=development
 PORT=3100
 HOST=0.0.0.0

-# Flashpoint paths
+# Flashpoint paths (only FLASHPOINT_PATH is needed - others are derived automatically)
 FLASHPOINT_PATH=D:/Flashpoint
-FLASHPOINT_DB_PATH=D:/Flashpoint/Data/flashpoint.sqlite
-FLASHPOINT_HTDOCS_PATH=D:/Flashpoint/Legacy/htdocs
-FLASHPOINT_IMAGES_PATH=D:/Flashpoint/Data/Images
-FLASHPOINT_LOGOS_PATH=D:/Flashpoint/Data/Logos
-FLASHPOINT_PLAYLISTS_PATH=D:/Flashpoint/Data/Playlists
-FLASHPOINT_GAMES_PATH=D:/Flashpoint/Data/Games

-# Game service
-GAME_SERVICE_PROXY_URL=http://localhost:22500
-GAME_SERVICE_GAMEZIP_URL=http://localhost:22501
+# Game service (derive URLs from host)
+GAME_SERVICE_HOST=localhost

 # Security (weak for dev only)
 JWT_SECRET=development-secret-change-in-production
@@ -585,18 +549,11 @@ NODE_ENV=production
 PORT=3100
 HOST=127.0.0.1

-# Flashpoint paths
+# Flashpoint paths (only FLASHPOINT_PATH is needed - others are derived automatically)
 FLASHPOINT_PATH=/data/flashpoint
-FLASHPOINT_DB_PATH=/data/flashpoint/Data/flashpoint.sqlite
-FLASHPOINT_HTDOCS_PATH=/data/flashpoint/Legacy/htdocs
-FLASHPOINT_IMAGES_PATH=/data/flashpoint/Data/Images
-FLASHPOINT_LOGOS_PATH=/data/flashpoint/Data/Logos
-FLASHPOINT_PLAYLISTS_PATH=/data/flashpoint/Data/Playlists
-FLASHPOINT_GAMES_PATH=/data/flashpoint/Data/Games

-# Game service
-GAME_SERVICE_PROXY_URL=http://localhost:22500
-GAME_SERVICE_GAMEZIP_URL=http://localhost:22501
+# Game service (derive URLs from host)
+GAME_SERVICE_HOST=game-service

 # Security (CHANGE THESE!)
 JWT_SECRET=CHANGE-THIS-TO-A-RANDOM-64-CHARACTER-STRING
@@ -612,7 +569,7 @@ LOG_FILE=/var/log/flashpoint-backend.log

 # Redis (enabled)
 REDIS_ENABLED=true
-REDIS_HOST=localhost
+REDIS_HOST=redis
 REDIS_PORT=6379
 REDIS_TTL=3600

@@ -648,9 +605,6 @@ LOG_LEVEL=warn
 # External URLs (game content fallback)
 EXTERNAL_FALLBACK_URLS=http://infinity.flashpointarchive.org/Flashpoint/Legacy/htdocs,http://infinity.unstable.life/Flashpoint/Legacy/htdocs/
 # Note: Image CDN URLs are automatically read from Flashpoint preferences
-
-# API URL (for frontend build)
-VITE_API_URL=https://flashpoint.example.com
 ```

 ## Validation and Defaults
@@ -680,18 +634,10 @@ export const config = envSchema.parse(process.env);
 These variables MUST be set or the application will fail to start:

 **Backend:**
- `FLASHPOINT_PATH`
- `FLASHPOINT_DB_PATH`
- `FLASHPOINT_HTDOCS_PATH`
- `FLASHPOINT_IMAGES_PATH`
- `FLASHPOINT_LOGOS_PATH`
- `FLASHPOINT_PLAYLISTS_PATH`
- `FLASHPOINT_GAMES_PATH`
+- `FLASHPOINT_PATH` (all other paths are derived automatically)

 **Game Service:**
- `FLASHPOINT_PATH`
- `FLASHPOINT_HTDOCS_PATH`
- `FLASHPOINT_GAMES_PATH`
+- `FLASHPOINT_PATH` (FLASHPOINT_HTDOCS_PATH and FLASHPOINT_GAMES_PATH are derived automatically)

 **Production (Backend):**
 - `JWT_SECRET` (must be changed from default)
@@ -706,8 +652,8 @@ Test configuration without starting services:
 cd backend
 node -e "require('dotenv').config(); console.log(process.env)"

-# Validate Flashpoint paths exist
-node -e "require('dotenv').config(); const fs=require('fs'); console.log(fs.existsSync(process.env.FLASHPOINT_DB_PATH) ? 'OK' : 'NOT FOUND')"
+# Validate Flashpoint path exists
+node -e "require('dotenv').config(); const fs=require('fs'); console.log(fs.existsSync(process.env.FLASHPOINT_PATH) ? 'OK' : 'NOT FOUND')"
 ```

 ## Security Best Practices
@@ -121,18 +121,12 @@ NODE_ENV=production
 PORT=3100
 HOST=127.0.0.1  # Only bind to localhost (Nginx will proxy)

-# Flashpoint paths
+# Flashpoint paths - only FLASHPOINT_PATH is needed
+# All other paths (DB, HTDOCS, IMAGES, LOGOS, PLAYLISTS, GAMES) are derived automatically
 FLASHPOINT_PATH=/data/flashpoint
-FLASHPOINT_DB_PATH=/data/flashpoint/Data/flashpoint.sqlite
-FLASHPOINT_HTDOCS_PATH=/data/flashpoint/Legacy/htdocs
-FLASHPOINT_IMAGES_PATH=/data/flashpoint/Data/Images
-FLASHPOINT_LOGOS_PATH=/data/flashpoint/Data/Logos
-FLASHPOINT_PLAYLISTS_PATH=/data/flashpoint/Data/Playlists
-FLASHPOINT_GAMES_PATH=/data/flashpoint/Data/Games

-# Game service (localhost)
-GAME_SERVICE_PROXY_URL=http://localhost:22500
-GAME_SERVICE_GAMEZIP_URL=http://localhost:22501
+# Game service host - URLs are constructed as http://${GAME_SERVICE_HOST}:22500 and :22501
+GAME_SERVICE_HOST=localhost

 # Security (CHANGE THESE!)
 JWT_SECRET=<generate-strong-random-secret-64-chars>
@@ -172,9 +172,9 @@ interface JWTPayload {
 #### Backend
 ```env
 FLASHPOINT_PATH=D:/Flashpoint
-FLASHPOINT_DB_PATH=D:/Flashpoint/Data/flashpoint.sqlite
-GAME_SERVICE_PROXY_URL=http://localhost:22500
-GAME_SERVICE_GAMEZIP_URL=http://localhost:22501
+# Note: All other paths (DB, HTDOCS, IMAGES, LOGOS, PLAYLISTS, GAMES) are derived automatically
+GAME_SERVICE_HOST=localhost
+# Note: Proxy and GameZip URLs are derived automatically from GAME_SERVICE_HOST
 DOMAIN=http://localhost:5173
 JWT_SECRET=your-secret-key
 JWT_EXPIRES_IN=1h
@@ -620,14 +620,10 @@ services:
      - PORT=3100
      - HOST=0.0.0.0
      - FLASHPOINT_PATH=/data/flashpoint
-      - FLASHPOINT_DB_PATH=/data/flashpoint/Data/flashpoint.sqlite
-      - FLASHPOINT_HTDOCS_PATH=/data/flashpoint/Legacy/htdocs
-      - FLASHPOINT_IMAGES_PATH=/data/flashpoint/Data/Images
-      - FLASHPOINT_LOGOS_PATH=/data/flashpoint/Data/Logos
-      - FLASHPOINT_PLAYLISTS_PATH=/data/flashpoint/Data/Playlists
-      - FLASHPOINT_GAMES_PATH=/data/flashpoint/Data/Games
-      - GAME_SERVICE_PROXY_URL=http://game-service:22500
-      - GAME_SERVICE_GAMEZIP_URL=http://game-service:22501
+      # Note: FLASHPOINT_DB_PATH, FLASHPOINT_HTDOCS_PATH, IMAGES_PATH, LOGOS_PATH, PLAYLISTS_PATH, GAMES_PATH
+      # are all derived automatically from FLASHPOINT_PATH
+      - GAME_SERVICE_HOST=game-service
+      # Note: Proxy and GameZip URLs are derived automatically from GAME_SERVICE_HOST
      - DOMAIN=http://localhost:${WEB_PORT:-80}
      - LOG_LEVEL=${LOG_LEVEL:-info}
    depends_on:
@@ -44,7 +44,7 @@
    "monorepo"
  ],
  "author": "",
-  "license": "MIT",
+  "license": "GPL-3.0",
  "devDependencies": {
    "concurrently": "^8.2.2",
    "prettier": "^3.2.4"