> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rndrntwrk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Countdown Announcements

> Time-based participation prompts for scheduling, launches, and synchronized engagement

<Info>**Status: Live**: This feature is operational.</Info>

Time-based participation prompts that count down to a target date/time with smooth card-flip transitions. Used for scheduling, launches, and synchronized engagement moments across the network.

## Architecture Flow

```
User → AnnouncementsPage → Backend API → Database
                ↓
        ControlPanelApp (loads & broadcasts)
                ↓
        BroadcastChannel (same browser) / WebSocket (OBS)
                ↓
        Overlay Page → AnnouncementsOverlay → FlipCountdown
```

## Components

### Frontend Components

1. **FlipCountdown.tsx** - Core countdown component
   * Real-time countdown calculation
   * Individual flip card per digit
   * Auto mode for smart unit visibility
   * Panchang-Bold font for numbers

2. **FlipCountdown.module.css** - 3D flip animations
   * Perspective transforms
   * Smooth easing transitions
   * Card shadows and depth effects

3. **AnnouncementsOverlay.tsx** - Overlay renderer
   * Handles all announcement styles
   * Manages placement and sizing
   * Integrates FlipCountdown component

4. **AnnouncementsPage.tsx** - Management UI
   * Create/edit/delete interface
   * Time presets (+10min, +1h, +1d, +1w)
   * Auto mode toggle
   * Live preview while editing
   * Past date validation

5. **ControlPanelApp.tsx** - State broadcaster
   * Loads announcements from backend
   * Broadcasts via BroadcastChannel
   * Sends to overlay page in real-time

### Backend Components

1. **model/model.go** - Database model
   * Announcement struct with countdown fields
   * JSON serialization tags for API responses

2. **handler/announcements.go** - API endpoints
   * CRUD operations
   * Countdown field validation
   * Special handling for countdown style

3. **Database Table**: `announcements`
   * Standard announcement fields
   * Countdown-specific fields:
     * `target_time` (TIMESTAMP)
     * `countdown_show_days` (BOOLEAN)
     * `countdown_show_hours` (BOOLEAN)
     * `countdown_show_minutes` (BOOLEAN)
     * `countdown_show_seconds` (BOOLEAN)
     * `countdown_auto_mode` (BOOLEAN)

## Data Flow

### 1. Creating a Countdown

```
User fills form → POST /api/announcements →
Backend validates → Saves to DB →
Returns announcement with ID →
Frontend refreshes list →
ControlPanelApp broadcasts to overlay
```

### 2. Displaying on Overlay

```
ControlPanelApp loads announcements (every 30s or on change) →
Broadcasts via BroadcastChannel →
Overlay page receives update →
AnnouncementsOverlay filters visible announcements →
FlipCountdown renders for 'countdown' style →
Updates every second with flip animations
```

## UX Features

### Smart Time Presets

* **+10 min** - Quick countdown for imminent events
* **+1 hour** - Short-term announcements
* **+1 day** - Next-day events
* **+1 week** - Weekly milestones

### Auto Mode

When enabled, automatically shows/hides units based on time remaining:

* Hides "Days" if \< 1 day
* Hides "Hours" if \< 1 hour
* Always shows minutes and seconds
* Keeps display clean and relevant

### Manual Mode

Full control over which units display:

* Toggle Days on/off
* Toggle Hours on/off
* Toggle Minutes on/off
* Toggle Seconds on/off

### Validation

* Prevents past dates with `min` attribute
* Shows warning if past date is detected
* Client-side validation before submission
* Backend validation for countdown requirements

### Live Preview

* Shows countdown while creating (before saving)
* Updates in real-time as settings change
* Also shows in standard Preview section
* Matches exact overlay appearance

## API Endpoints

### GET /v1/announcements

Returns all announcements for authenticated user, including countdown fields.

**Response**:

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 1,
      "type": "manual",
      "text": "Countdown",
      "style": "countdown",
      "placement": "top-bar",
      "duration": 5,
      "backgroundColor": "#000000",
      "textColor": "#ffffff",
      "fontSize": 16,
      "is_visible": true,
      "target_time": "2026-06-15T20:00:00Z",
      "countdown_show_days": true,
      "countdown_show_hours": true,
      "countdown_show_minutes": true,
      "countdown_show_seconds": true,
      "countdown_auto_mode": false
    }
  ]
}
```

### POST /v1/announcements

Creates a new countdown announcement.

**Request**:

```json theme={null}
{
  "type": "manual",
  "text": "",
  "style": "countdown",
  "placement": "center",
  "duration": 10,
  "backgroundColor": "#000000",
  "textColor": "#ffffff",
  "fontSize": 16,
  "isVisible": true,
  "targetTime": "2026-06-16T15:00:00Z",
  "countdownShowDays": true,
  "countdownShowHours": true,
  "countdownShowMinutes": true,
  "countdownShowSeconds": true,
  "countdownAutoMode": false
}
```

### PUT /v1/announcements/\{id}

Updates an existing countdown.

### DELETE /v1/announcements/\{id}

Deletes a countdown announcement.

## Placement Options

All standard placement options supported:

* `full-screen` - Full viewport
* `top-bar` - Top center strip
* `bottom-bar` - Bottom center strip
* `center` - Dead center
* `top-left` - Upper left corner
* `top-right` - Upper right corner
* `bottom-left` - Lower left corner
* `bottom-right` - Lower right corner

## Styling

### Colors

* `backgroundColor` - Card background color
* `textColor` - Digit and label color

### Typography

* Uses **Panchang-Bold** font (same as headers)
* Font size scales all elements proportionally
* Tabular numbers for consistent digit width

### Animations

* 3D flip animation on digit change
* 0.6s duration with cubic-bezier easing
* Smooth, professional transitions

## Troubleshooting

<AccordionGroup>
  <Accordion title="Countdown Not Showing on Overlay">
    **Check**:

    1. Is `isVisible` set to `true`?
    2. Is the streamer ID correct in the overlay URL?
    3. Open browser console - any errors?
    4. Check if BroadcastChannel is working (same browser)

    **Solution**:

    * Ensure countdown announcement has `is_visible = true` in database
    * Verify ControlPanelApp is broadcasting (check console logs)
    * Refresh overlay page to re-establish BroadcastChannel
  </Accordion>

  <Accordion title="Preview Erratic">
    **Issue**: Preview flickering or not updating properly.

    **Solution**:

    * Fixed by ensuring `previewAnnouncements` includes form data when editing
    * Only shows preview when form is open AND visibility is ON
    * Uses consistent field mapping
  </Accordion>

  <Accordion title="400 Bad Request">
    **Issue**: Backend rejecting countdown creation.

    **Causes**:

    1. Missing `targetTime` for countdown style
    2. Invalid date format
    3. Missing JSON tags on backend model

    **Solutions**:

    * Client validates `targetTime` before submission
    * Backend uses default "Countdown" text for empty text field
    * All model fields have proper JSON tags
  </Accordion>
</AccordionGroup>

## Performance

* **Update Frequency**: 1 second (minimal CPU)
* **Animation Cost**: CSS transforms (GPU accelerated)
* **Network**: No polling (BroadcastChannel is local)
* **Database**: Indexed on `target_time` for queries