Timer System Documentation

Architecture Overview

The timer system consists of server-side and client-side components working together through WebSockets for real-time updates.

Core Components

1. Server-Side Timer Logic (server/routes.ts)

   • Manages timer state in the database
   • Broadcasts timer updates to connected clients
   • Handles timer phase transitions
   • Processes timer commands (start/reset)

2. WebSocket Communication

   • Server establishes WebSocket server on /ws path
   • Clients connect and receive real-time updates
   • Initial state sent on connection
   • Periodic ticks update time remaining

3. Global Timer State (client/src/lib/timer-state.ts)

   • Centralized state management for the client
   • Handles time synchronization with server
   • Manages phase transitions

4. Timer UI Components

   • SafeZoneTimer - Visual display component
   • TimerDetails - Admin panel component
   • Both consume global timer state

Timer Phases

The timer has four phases:

• green: Initial phase
• yellow: Middle phase
• warning: Final phase
• stopped: Inactive state

Key Implementation Details

Server-Side Timer Logic

• Timer ticks process at 100ms intervals but only update when necessary
• Phase transitions occur automatically when timeLeft reaches zero
• Updates broadcast to all connected WebSocket clients
• All timer data stored in database via storage interface

WebSocket Implementation

• Server maintains a Set of connected clients
• Updates broadcast to all connected clients
• Includes ping mechanism to keep connections alive
• Initial state sent on new connections

Time Synchronization

• Server is the source of truth for time
• Client estimates server time offset for smooth animations
• Animation frames handle visual countdown between WebSocket updates

Admin Controls

• Authenticated admin users can start/reset the timer
• Update timer configuration (base times, extensions)
• Timer state changes immediately broadcast to all clients

Making Changes

1. Modify Timer Configuration: Edit the schema in shared/schema.ts if you need to add new timer properties.

2. Change Phase Logic: Update the phase transition logic in the interval handler in server/routes.ts.

3. UI Styling: Phase styles are defined in safe-zone-timer.tsx with color mappings.

4. Add New Features:

   • Server-side changes: Modify routes.ts to add new endpoints
   • Client-side changes: Update the global timer state in timer-state.ts

5. Authentication: Authentication requirements for timer control are in routes.ts. Timer operations require admin authentication.

Flow of Data

1. Admin triggers timer action via API
2. Server updates database
3. WebSocket broadcasts update to all clients
4. Clients update global timer state
5. UI components react to state changes
6. Animation frames provide smooth countdown