PWA fixed
added systemd service howto traefik nginix set_real_ip_from improved readme visuals fixed on mobile labels removed updated readme fixed visuals overlay for the hotkey disable screen lock clean up git precommit hooks clean up clean up update check for update feature added build-time information fixed date clean up added hook script fix fix fix hooks fixed webhook setup players stay in run all timers mode mqtt mqtt allways connected mqtt messages work capturing mqtt in edit player mqtt in Setup updated readme state of the mqtt Global Pass turn offline mode docs: update documentation to reflect current codebase and MQTT features - Update README.md with global MQTT commands - Enhance architecture.md with comprehensive data model and MQTT state - Update development.md with project structure and workflow - Remove redundant script listings - Fix formatting and organization rebase
This commit is contained in:
124
docs/architecture.md
Normal file
124
docs/architecture.md
Normal file
@@ -0,0 +1,124 @@
|
||||
## Data Model
|
||||
|
||||
The application maintains a comprehensive data model for managing game state:
|
||||
|
||||
```typescript
|
||||
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)
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Reference in New Issue
Block a user