# Scoreboard deployment and operating guide

Updated: 2026-07-01

## Supplied files

- `scorebord_optimized_web.zip` — uploadable website package.
- `pppl_scoreboard_clean_database.sql` — recommended for a new tournament; schema only, with no old teams or matches.
- `pppl_scoreboard_database.sql` — the original uploaded database export with historical test/event data; keep as a backup and do **not** place it in `public_html`.
- The admin token for this build is shown below. Change it before the tournament.

## Admin token

`xYmqXZloJVZ3fHtJs2lIL7t68zeb7bb_`

The control page asks for this token. It is stored only in the browser's `sessionStorage`, so closing the tab/session may require entering it again.

Change the token in `scoreboard_config.php` before public use. Use a long, random value. The same token must remain on the server for the whole control session.

## Deployment

1. Create a MySQL/MariaDB database and database user in the hosting control panel.
2. For a new tournament, import `pppl_scoreboard_clean_database.sql` using phpMyAdmin. Import the original `pppl_scoreboard_database.sql` only when you intentionally want its existing teams and match history.
3. Extract `scorebord_optimized_web.zip` on your computer.
4. Edit the fallback values in `db.php`:
   - database host
   - database name
   - database username
   - database password
5. Upload the **contents of the `scorebord` folder** to the desired web directory, for example `public_html/scorebord/`.
6. Ensure `api/_state/` and `api/_state/state.json` are writable by PHP. Start with normal hosting permissions; use directory permission `775` only if updates do not reach the screen. Avoid `777`.
7. Use HTTPS.
8. Open `control.php`, enter the admin token, and test a temporary match.
9. Open `screen.php` on the laptop/LED browser.

Delete any uploaded ZIP archive after extraction. Never upload the SQL export into a publicly accessible directory.

## LED setup

The physical 12 ft × 8 ft size is a 3:2 aspect ratio, but the important setting is the LED controller's HDMI input resolution. In the laptop display settings:

1. Use **Extend these displays**, not Duplicate.
2. Select the LED display and use the resolution recommended by the LED processor/controller.
3. Move the browser window to the LED display.
4. Open `screen.php`, enable sound with the on-screen button if needed, and enter browser full-screen mode.
5. Disable laptop sleep, screen timeout, automatic updates, and notifications for the event period.

The revised CSS supports portrait phones, landscape phones, tablets, 16:9 displays, and 3:2 LED output. Mobile mode uses a compact two-row layout and may scroll only on unusually short screens.

## Server request design

The original project made these automatic PHP/MySQL reads over sixteen 40-minute matches:

- `screen.php`: one request every 700 ms — about **54,857** requests.
- `control.php`: one live request every second — **38,400** requests.
- `control.php`: one full initialization every five seconds — **7,680** requests.

That is about **100,937 automatic dynamic reads**, excluding score actions.

The revised build polls the small static file `api/_state/state.json`. PHP/MySQL is called when its version changes, plus an occasional safety refresh. During a live match the screen checks the static marker every second; completed/waiting screens check every ten seconds. This preserves fast updates without continuously querying the database.

A browser cannot know that the next match started with literally zero communication. The alternatives are polling or a persistent SSE/WebSocket connection. On PHP shared hosting, a persistent SSE request occupies a PHP worker, so this build deliberately uses the lightweight static marker. The old `events.php` SSE endpoint is disabled.

## Security

All APIs that change scores, teams, settings, matches, or display modes require the `X-Scoreboard-Token` header. `control.php` adds it automatically after the token prompt. The public LED screen only uses read-only endpoints.

Keep these precautions:

- Use HTTPS so the token is encrypted in transit.
- Do not share the admin token or leave `control.php` open on public devices.
- Rotate the token if it may have been exposed.
- Keep database credentials unique to this application.
- Back up the database before the tournament and after major stages.
- Do not remove the supplied `.htaccess` files unless equivalent server rules are configured.

## Errors corrected

- Added true portrait/mobile responsiveness and dynamic viewport support.
- Removed the unnecessary database connection from the initial `screen.php` page load.
- Replaced continuous 700 ms PHP polling with adaptive static-marker synchronization.
- Replaced continuous control-page polling with the same synchronization method.
- Removed the points-table rebuild/write from every `init.php` read.
- Rebuilds points only when a result can change, instead of after every live ball.
- Fixed innings elapsed time not being saved because SQL updated `status` before evaluating the old status.
- Fixed a wide/no-ball at the beginning of a new over not appearing in “This Over.”
- Added locking and a Windows fallback to the update marker writer.
- Added admin-token protection to all modifying APIs and to control initialization data.
- Removed raw database exception details from public responses.
- Disabled the unused shared-host-unfriendly SSE endpoint.
- Removed unused duplicate/old API files from the deployable package.
- Added no-cache headers and basic server file protections.

## Media files still missing

The code references these files, but they were not present in the uploaded project:

- `assets/sounds/four.mp3`
- `assets/sounds/freehit.mp3`
- `assets/sounds/game-on.mp3`
- `assets/sounds/win.mp3`
- `assets/sounds/milestone.mp3`
- `assets/sounds/special.mp3`
- `assets/sounds/timer.mp3`
- `assets/videos/theme-song.mp4`

Missing sounds fail silently; the visual scoreboard still works. Add correctly named files before the event if those effects are required.

## Event-day checks

- Test from the actual venue network and the actual LED processor.
- Test score add, edit, delete, pause, resume, innings break, second innings, match completion, super over, points table, sponsor screen, and tournament completion.
- Keep only one scoring control page active unless multiple operators are intentional.
- Keep a local backup of the website files and a recent SQL export.
- Verify `api/_state/state.json` changes its `version` after a score action.
- Verify the LED screen changes within roughly one second during live play.

Shared-host resource limits vary by plan and can change. This optimization substantially lowers PHP/MySQL load, but the current hosting account limits should still be checked in the provider dashboard and tested before the event.
