nexus-timer/docs/architecture.md

Data Model

The application maintains a comprehensive data model for managing game state:

interface Player {
  id: string;                    // Unique identifier for the player
  name: string;                  // Player's name
  avatar: string | null;         // Player's avatar (can be null for default)
  initialTimerSec: number;       // Initial timer value in seconds
  currentTimerSec: number;       // Current timer value in seconds
  hotkey: string | null;         // Keyboard hotkey for player control
  mqttChar: string | null;       // MQTT character for player control
  isSkipped: boolean;           // Whether the player is skipped
  isTimerRunning: boolean;       // Whether the player's timer is running
  isCurrent: boolean;           // Whether this is the current player
  isNext: boolean;              // Whether this is the next player
}

interface GameState {
  players: Player[];            // Array of all players
  currentPlayerIndex: number;   // Index of the current player
  gameMode: 'normal' | 'all-timers'; // Current game mode
  gameRunning: boolean;         // Whether the game is currently running
  isMuted: boolean;            // Whether audio is muted
  theme: 'light' | 'dark';      // Current theme
  mqttBrokerUrl: string;        // MQTT broker connection URL
  mqttConnectDesired: boolean;  // Whether MQTT connection is desired
  mqttConnected: boolean;       // Current MQTT connection status
  mqttReconnectAttempts: number; // Number of reconnection attempts
  mqttError: string | null;     // Current MQTT error state
  
  // Global Hotkey Controls
  globalHotkeyStopPause: string | null; // Hotkey for global stop/pause
  globalHotkeyRunAll: string | null;    // Hotkey for run all timers
  globalHotkeyPassTurn: string | null;  // Hotkey for global pass turn
  
  // Global MQTT Controls
  globalMqttStopPause: string | null;   // MQTT character for global stop/pause
  globalMqttRunAll: string | null;      // MQTT character for run all timers
  globalMqttPassTurn: string | null;    // MQTT character for global pass turn
}

Build-time Information & Service Worker Versioning

The application incorporates build-time information and a mechanism for service worker updates:

1. Version Management

   • Build timestamp
   • Git commit hash
   • Environment variables

2. Service Worker

   • Automatic updates
   • Cache management
   • Offline-first approach
   • Update notifications

3. Build Process

   • Environment-specific configurations
   • Asset optimization
   • Code splitting
   • Tree-shaking

This architecture ensures a maintainable, scalable, and performant application that meets the requirements of a multi-player timer system with remote control capabilities.

• Minimalist Design: Focus on clarity and ease of use. Avoid clutter.
• Large, Clear Timers: Timers should be easily readable at a glance.
• Color Coding: Use color to indicate timer state (e.g., green for running, red for negative time, grey for skipped).
• Responsive Layout: The UI should adapt to different (mobile phone) screen sizes.
• Touch-Friendly: Buttons and interactive elements should be large enough for easy tapping.

Tech Stack

• HTML5: For structuring the user interface.
• CSS3: For styling and visual presentation, including animations. Consider a CSS framework like Tailwind CSS for rapid prototyping.
• JavaScript: For application logic, timer functionality, and event handling.
• MQTT.js for MQTT communication
• Web Audio API: For audio feedback (ticking sounds, alerts).
• Browser API: For capturing Players' photo.
• Screen Wake Lock API: For preventing of the screen lock in a PWA.
• Local Storage/IndexedDB: For persistent storage of player data, timer states, and settings.
• Service Worker: Essential for PWA functionality (offline access, push notifications - potential future feature).
• Manifest File: Defines the PWA's metadata (name, icons, theme color).
• Web Framework: Vith Vite (Vue.js)
• Tailwind CSS: Utility-first CSS framework for rapid UI development.

Data Model (Conceptual for Setup)

{
  "players": [
    {
      "id": "1", "name": "Alice", "avatar": "image_data_or_default",
      "initialTimerSec": 3600, "currentTimerSec": 3600,
      "hotkey": "a", "mqttChar": "x", "isSkipped": false
    }
  ],
  "globalHotkeyStopPause": "s",
  "globalMqttStopPause": "p",
  "globalHotkeyRunAll": "r",
  "globalMqttRunAll": "t",
  "globalHotkeyPassTurn": "n",
  "globalMqttPassTurn": "m",
  "mqttBrokerUrl": "ws://localhost:9001",
  "mqttConnectDesired": true,
  "currentPlayerIndex": 0,
  "gameMode": "normal",
  "isMuted": false,
  "theme": "light"
}

Build-time Information & Service Worker Versioning

The application incorporates build-time information and a mechanism for service worker updates:

1. Build Timestamp:

   • The build date and time are automatically injected into the application during the Vite build process.
   • This is configured in vite.config.js using Vite's define feature, making import.meta.env.VITE_APP_BUILD_TIME available in the Vue components.
   • The timestamp (formatted for the sk-SK locale) is displayed on the "About" screen (src/views/InfoView.vue).

2. Service Worker Cache Versioning:

   • The CACHE_VERSION constant within the service worker (src/sw.js) is also dynamically generated during the Vite build.
   • vite.config.js uses the define feature to replace a placeholder (__APP_CACHE_VERSION__) in src/sw.js with a unique version string. This string typically incorporates the application's version from package.json and a build timestamp (Date.now()) to ensure uniqueness.
   • The src/sw.js file is configured as a separate Rollup entry point in vite.config.js so that Vite processes it and performs this replacement, outputting the final service-worker.js to the dist directory root.
   • When a new version of the app is deployed with a changed service-worker.js (due to this new CACHE_VERSION), the browser detects the difference. The updated service worker installs, and upon activation, it clears out old caches associated with previous versions. This mechanism is key to how the PWA updates and provides users with the latest assets. The "Check for Update" feature on the "About" screen manually triggers the browser to check for a new service-worker.js file.