nexus-timer/docs/architecture.md

Table of Contents

1. UI/UX Considerations
2. Tech Stack
3. Data Model (For AI Generation)
4. Build-time Information & Service Worker Versioning

UI/UX Considerations

• 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",
  "mqttBrokerUrl": "ws://localhost:9001",
  "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.