dotcom-arcade/docs/12-reference

Reference Documentation

This directory contains comprehensive reference materials for the Dotcom Arcade application, including database schemas, type definitions, terminology, and dependency information.

Contents

Database Schema Reference

Complete database schema documentation for both databases used in the application:

• Flashpoint Database (flashpoint.sqlite)

  • Read-only game metadata database
  • Tables: game, game_data, platform, tag, playlist, etc.
  • Indexes and relationships
  • Query patterns and best practices

• User Database (user.db)

  • Application-managed user data
  • Tables: users, roles, permissions, activity_logs, play_sessions, etc.
  • Migration management
  • RBAC implementation

Use this when:

• Writing database queries
• Understanding data relationships
• Designing new features requiring data storage
• Debugging data issues
• Planning database migrations

---

Type Definitions Reference

TypeScript type and interface definitions used throughout the codebase:

• Game Types: Game, GameFilters, FilterOptions, Playlist, GameLaunchData
• Authentication Types: User, AuthTokens, LoginCredentials, Permission, Role
• User Management Types: UserDetails, CreateUserData, UpdateUserData, ActivityLog
• Play Tracking Types: PlaySession, GameStats, UserStats
• UI State Types: AuthState, UIState, ThemeState
• Theme Types: ThemeMode, PrimaryColor, ColorPalette
• Pagination Types: PaginatedResult, PaginatedResponse
• JWT Types: JWTPayload
• API Response Types: SuccessResponse, ErrorResponse

Use this when:

• Writing new components or services
• Understanding data structures
• Implementing API endpoints
• Adding new features
• Refactoring code

---

Glossary

Definitions of technical terms, project-specific terminology, and architectural concepts:

• Project-Specific Terms: Flashpoint, Flashpoint Launcher, htdocs, library, curation
• Technical Terms: JWT, RBAC, CORS, bcrypt, SQLite, hot-reload, middleware
• Architecture Terms: Monorepo, service layer, separation of concerns, state management
• Database Terms: Migration, foreign key, index, transaction, schema
• Authentication: Access token, refresh token, permission, guest mode, session
• Frontend Terms: SPA, HMR, React Query, Zustand, Tailwind CSS, virtualization
• Game & Emulation: Flash, Ruffle, SWF, ActionScript, HTML5 games, ZIP mounting
• Development Terms: TypeScript, tsx, Vite, ESLint, Docker, environment variables

Use this when:

• Onboarding new developers
• Understanding unfamiliar terminology
• Writing documentation
• Discussing architecture
• Learning about specific technologies

---

External Dependencies

Comprehensive reference for all npm packages used across the monorepo:

• Backend Dependencies: Express, BetterSqlite3, bcrypt, JWT, axios, winston, node-stream-zip (game module)
• Frontend Dependencies: React, Vite, TanStack Query, Zustand, Tailwind CSS, Radix UI
• Shared Development Tools: TypeScript, ESLint, tsx, concurrently
• License Information: Summary of all licenses used
• Alternative Considerations: Packages considered but not chosen
• Dependency Management: Update processes and best practices

Use this when:

• Adding new dependencies
• Understanding why specific packages were chosen
• Updating dependencies
• Auditing licenses
• Troubleshooting package issues
• Planning architecture changes

---

Quick Reference

Common Database Queries

Get Game by ID

SELECT * FROM game WHERE id = ?;

Get User with Permissions

SELECT u.*, r.name as role_name, GROUP_CONCAT(p.name) as permissions
FROM users u
INNER JOIN roles r ON r.id = u.role_id
LEFT JOIN role_permissions rp ON rp.role_id = r.id
LEFT JOIN permissions p ON p.id = rp.permission_id
WHERE u.id = ?
GROUP BY u.id;

Get User Play Statistics

SELECT game_id, game_title, total_plays, total_playtime_seconds
FROM user_game_stats
WHERE user_id = ?
ORDER BY last_played_at DESC
LIMIT 10;

---

Common Type Patterns

API Response with Pagination

interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    total: number;
    page: number;
    limit: number;
    totalPages: number;
  };
}

Game Filters

interface GameFilters {
  search?: string;
  platform?: string;
  library?: string;
  tags?: string;
  sortBy?: string;
  sortOrder?: 'asc' | 'desc';
  page?: number;
  limit?: number;
}

JWT Payload

interface JWTPayload {
  userId: number;
  username: string;
  role: string;
}

---

Environment Variables Reference

Backend

FLASHPOINT_PATH=D:/Flashpoint
# 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

Frontend

# No environment variables required for local development
# API calls are proxied through Vite (dev) or Nginx (production)
# Optional: displayed app version. Defaults to the release tag via `git
# describe`, then to frontend/package.json. The Docker build has no .git, so
# CI passes the tag through the VERSION build arg instead.
VITE_APP_VERSION=1.0.38

Game Service

FLASHPOINT_PATH=D:/Flashpoint
# Note: HTDOCS and Games paths are derived automatically from FLASHPOINT_PATH
PROXY_PORT=22500
GAMEZIPSERVER_PORT=22501

---

Common Permissions

Permission	Description
games.read	View and browse games
games.play	Play games in browser
games.download	Download game files
playlists.read	View playlists
playlists.create	Create new playlists
playlists.update	Update existing playlists
playlists.delete	Delete playlists
users.read	View user accounts
users.create	Create new user accounts
users.update	Update user accounts
users.delete	Delete user accounts
roles.read	View roles and permissions
roles.update	Update roles and permissions
settings.read	View system settings
settings.update	Update system settings
activities.read	View activity logs

---

Default Roles

Role	Priority	Default Permissions
admin	100	All permissions
user	50	All except users., roles., settings.*, activities.read
guest	0	games.read, playlists.read

---

Port Reference

Service	Port	Purpose
Backend	3100	REST API + game content routes
Frontend	5173	Vite development server
Game Content (Backend)	3100	/game-proxy/* and /game-zip/*

---

Usage Guidelines

When to Use Which Reference

• Need database structure? → Database Schema Reference
• Need type definitions? → Type Definitions Reference
• Need term definition? → Glossary
• Need package info? → External Dependencies

Keeping References Up-to-Date

Reference documentation should be updated when:

• Database schema changes (new tables, columns, indexes)
• New types or interfaces are added
• New terminology is introduced
• Dependencies are added, removed, or significantly changed
• Major architectural changes occur

Contributing to References

When updating reference documentation:

1. Be comprehensive: Include all relevant details
2. Be consistent: Follow existing format and structure
3. Be clear: Use simple language and examples
4. Cross-reference: Link to related documentation
5. Include examples: Show real-world usage
6. Keep organized: Maintain logical grouping

---

Related Documentation

Architecture

• System Architecture
• Service Communication
• Data Flow Diagrams

Backend

• Backend Architecture
• Database Services
• API Reference

Frontend

• Frontend Architecture
• State Management
• Component Overview

Backend Game Module

• Game Service Architecture (now integrated into backend)
• Proxy Server
• ZIP Manager

API Reference

• Authentication API
• Games API
• Users API

Development

• Setup Guide
• Coding Standards
• Common Pitfalls

---

Feedback

If you find errors, outdated information, or missing content in these references, please:

1. Create an issue in the project repository
2. Submit a pull request with corrections
3. Contact the documentation maintainer

Good reference documentation is essential for project success. Help keep it accurate and useful!