# EJIC Display Service (fka-iaido-sm-2026)

Tournament display service built with static HTML, browser-side JavaScript, and PHP JSON endpoints.

## Runtime Overview

- Frontend pages are served from `html/`.
- Shared JS/CSS/config moved under `html/App/`.
- Overlay pages live under `html/Streaming/`.
- Media assets and spreadsheet config live under `html/Media/`.
- Main dynamic data flow:
  - `html/App/getMatches.php` -> match JSON
  - `html/getAnnouncements.php` -> announcements JSON
  - `html/saveAnnouncements.php` -> persists announcements

## Current Directory Structure

```text
fka-iaido-sm-2026/
  Dockerfile
  README.md
  html/
    index.html
    internalTools.html
    displayMatches.php
    displayMatchesMulti.html
    announcerScreen.php
    announcementsManager.php
    announcementsDisplay.php
    playerScreen.php
    managerScreen.php
    getAnnouncements.php
    saveAnnouncements.php
    displayMatchesAll.html
    displayMatchesAllFront.html
    App/
      styles.css
      matchConstants.js
      matchHelpers.js
      eventSettingsLoader.js
      eventSettings.json
      getMatches.php
    Streaming/
      currentMatchOverlay.php
      announcementOverlay.php
    Media/
      config.php
      ... media files (logos/photos/flags)
```

## Folder Responsibilities

- `html/`
  - Entry and operator pages.
  - Announcement API endpoints (`getAnnouncements.php`, `saveAnnouncements.php`).
- `html/App/`
  - Shared application assets and logic:
    - `styles.css` global styles.
    - `matchConstants.js` path and column constants.
    - `matchHelpers.js` rendering/data helpers.
    - `eventSettingsLoader.js` loads and applies event settings.
    - `eventSettings.json` single source of event configuration.
    - `getMatches.php` match data endpoint with best-effort caching.
- `html/Streaming/`
  - Stream overlays:
    - `currentMatchOverlay.php`
    - `announcementOverlay.php`
- `html/Media/`
  - Spreadsheet config and static media resources.

## File Responsibilities (Key Files)

- `html/index.html`
  - Main landing/navigation page for public display links.
- `html/internalTools.html`
  - Internal tools landing page.
- `html/displayMatches.php`
  - Main match list display (current/upcoming/done).
- `html/displayMatchesMulti.html`
  - Multi-court frame composition page.
- `html/announcerScreen.php`
  - Announcer/operator view with per-court upcoming flow + announcements.
- `html/announcementsManager.php`
  - Edit/save announcements UI.
- `html/announcementsDisplay.php`
  - Read-only announcement board display.
- `html/playerScreen.php`
  - Player lookup and match timeline view.
- `html/managerScreen.php`
  - Country lookup and match timeline view.
- `html/getAnnouncements.php`
  - Announcement read endpoint backed by JSON cache file.
- `html/saveAnnouncements.php`
  - Announcement write endpoint.
- `html/App/getMatches.php`
  - Match read endpoint (Google Sheets -> JSON), with best-effort cache.
- `html/App/eventSettingsLoader.js`
  - Fetches `eventSettings.json`, merges defaults, applies settings to page DOM.
- `html/App/eventSettings.json`
  - Event-level configuration (titles, branding, links, assets, feature toggles).
- `html/App/matchConstants.js`
  - Data column indices and path prefixes, auto-adjusted for normal vs streaming pages.
- `html/App/matchHelpers.js`
  - Shared player/photo/flag rendering helpers.
- `html/Streaming/currentMatchOverlay.php`
  - Overlay for current match and previous/next match transitions.
- `html/Streaming/announcementOverlay.php`
  - Overlay ticker for announcements per court.
- `html/Media/config.php` (NOT ON REPO)
  - Spreadsheet/API configuration source for match endpoint.

## What Changed (Refactor Summary)

- Created `html/App/` and moved shared JS/CSS/config there.
- Created `html/Streaming/` and moved overlay pages there.
- Renamed `eventSettings.js` -> `eventSettingsLoader.js`.
- Moved settings file to `html/App/eventSettings.json`.
- Updated all `src`, `href`, `fetch`, and settings path references for new directories.
- Updated `html/App/getMatches.php` to use absolute include path and robust cache strategy.
- Added event feature toggles:
  - `features.usePhotos`
  - `features.useFlags`
- Implemented class-based media hiding:
  - loader toggles `body.hide-photos` and `body.hide-flags`
  - CSS hides photo/flag containers without breaking layout structure.

## Event Settings

Settings file:

- `html/App/eventSettings.json`

Main sections:

- `pageTitles`
- `branding`
- `links`
- `assets`
- `features`

Feature toggles:

- `features.usePhotos: true|false`
- `features.useFlags: true|false`

Behavior:

- `eventSettingsLoader.js` applies classes on `<body>`:
  - `hide-photos` when photos are disabled.
  - `hide-flags` when flags are disabled.

## Path/Reference Conventions

- From pages in `html/`:
  - app assets: `App/...`
  - media: `Media/...`
- From pages in `html/Streaming/`:
  - app assets: `../App/...`
  - media/api in html root: `../...`
- `matchConstants.js` auto-detects streaming context and prefixes paths accordingly.

## Operational Notes & Troubleshooting

### Match endpoint cache permissions

`html/App/getMatches.php` tries cache directories in order:

1. `html/cache`
2. `html/App/cache`

If neither is writable, endpoint still attempts live fetch from Google Sheets (best effort caching).

If server still returns 500:

- Verify PHP can read `html/Media/config.php`.
- Verify outbound HTTP from PHP to Google Sheets is allowed.
- Verify file permissions for cache candidate directories.

### Announcements cache permissions

`html/getAnnouncements.php` and `html/saveAnnouncements.php` use `html/cache/announcements.json`.
Ensure `html/cache` is writable by web server user.

### Event settings not applying

Check browser console for loader messages:

- `[eventSettings] Loaded from ...`
- `[eventSettings] Failed loading ...`

And verify these URLs are reachable:

- `/html/App/eventSettingsLoader.js`
- `/html/App/eventSettings.json`

### Docker caveat

Current `Dockerfile` line:

- `COPY html/* /var/www/html/`

This can miss nested directory content (`App/`, `Streaming/`, deeper media). Prefer recursive copy for production images.

## Quick Post-Deploy Verification

1. Open `/html/` and confirm title/link updates from settings.
2. Open `/html/displayMatches.php?court=A` and ensure matches load.
3. Open `/html/Streaming/currentMatchOverlay.php?court=A`.
4. Open `/html/Streaming/announcementOverlay.php?court=A`.
5. Check browser Network for 404/500 on:
   - `App/eventSettingsLoader.js`
   - `App/eventSettings.json`
   - `App/getMatches.php`
   - `getAnnouncements.php`
   - `App/styles.css`
   - required `Media/...` assets