> ## Documentation Index
> Fetch the complete documentation index at: https://285e39fd5e337e58f16290.sightscreen.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration reference

> All environment variables and their purposes.

Every environment variable used by the Sightscreen backend, organized by category. All variables are read at startup unless noted otherwise.

## Quick reference

<Accordion title="Server">
  | Variable               | Required | Default      | Purpose                                                         |
  | ---------------------- | -------- | ------------ | --------------------------------------------------------------- |
  | `PORT`                 | No       | `3000`       | HTTP server port                                                |
  | `NODE_ENV`             | No       | `production` | Environment mode. Set to `development` for dev mode auth bypass |
  | `CORS_ALLOWED_ORIGINS` | No       | `*`          | Comma-separated list of allowed CORS origins                    |
</Accordion>

<Accordion title="AWS">
  | Variable                | Required | Default | Purpose                                                                    |
  | ----------------------- | -------- | ------- | -------------------------------------------------------------------------- |
  | `AWS_REGION`            | Yes      | --      | AWS region for all services (DynamoDB, etc.)                               |
  | `AWS_ACCESS_KEY_ID`     | No       | --      | Explicit credentials. Omit to use instance role / default credential chain |
  | `AWS_SECRET_ACCESS_KEY` | No       | --      | Explicit credentials. Omit to use instance role / default credential chain |

  <Note>
    In production (ECS/EC2), use IAM roles instead of explicit credentials. The AWS SDK automatically discovers them.
  </Note>
</Accordion>

<Accordion title="Cognito">
  | Variable               | Required | Default | Purpose                                       |
  | ---------------------- | -------- | ------- | --------------------------------------------- |
  | `COGNITO_USER_POOL_ID` | Yes      | --      | Cognito User Pool ID for JWT validation       |
  | `COGNITO_CLIENT_ID`    | Yes      | --      | Cognito App Client ID for audience validation |
</Accordion>

<Accordion title="Admin">
  | Variable        | Required | Default | Purpose                                          |
  | --------------- | -------- | ------- | ------------------------------------------------ |
  | `ADMIN_API_KEY` | Yes      | --      | Static API key for server-to-server admin access |

  <Warning>
    Treat this like a password. Rotate it if compromised.
  </Warning>
</Accordion>

<Accordion title="SportMonks">
  | Variable               | Required | Default | Purpose                                        |
  | ---------------------- | -------- | ------- | ---------------------------------------------- |
  | `SPORTMONKS_API_TOKEN` | Yes      | --      | API token for SportMonks cricket data API      |
  | `SPORTMONKS_SEASON_ID` | Yes      | --      | The season ID to query for fixtures and scores |
</Accordion>

<Accordion title="DynamoDB tables">
  All table names default to the values shown. Override them to use custom table names (e.g., per-environment prefixes).

  | Variable                        | Default                      | Purpose                                  |
  | ------------------------------- | ---------------------------- | ---------------------------------------- |
  | `DYNAMODB_USERS_TABLE`          | `sightscreen-users`          | User profiles                            |
  | `DYNAMODB_MATCHES_TABLE`        | `sightscreen-matches`        | Match/fixture metadata                   |
  | `DYNAMODB_SCORES_TABLE`         | `sightscreen-scores`         | Live score data                          |
  | `DYNAMODB_LEAGUES_TABLE`        | `sightscreen-leagues`        | League definitions                       |
  | `DYNAMODB_TEAMS_TABLE`          | `sightscreen-teams`          | Team data and overrides                  |
  | `DYNAMODB_DEVICES_TABLE`        | `sightscreen-devices`        | APNs device tokens                       |
  | `DYNAMODB_SUBSCRIPTIONS_TABLE`  | `sightscreen-subscriptions`  | Match follow subscriptions               |
  | `DYNAMODB_REPLAY_MATCHES_TABLE` | `sightscreen-replay-matches` | Active replay match state                |
  | `DYNAMODB_TAPES_TABLE`          | `sightscreen-tapes`          | Recorded match tapes for replay          |
  | `DYNAMODB_APP_CONFIG_TABLE`     | `sightscreen-app-config`     | App configuration (version, maintenance) |
</Accordion>

<Accordion title="Live Activities & orchestration">
  | Variable                     | Required | Default | Purpose                                                                         |
  | ---------------------------- | -------- | ------- | ------------------------------------------------------------------------------- |
  | `LIVE_ACTIVITIES_TABLE`      | Yes      | --      | DynamoDB table for Live Activity records (tokens, state, match association)     |
  | `ACTIVE_MATCHES_TABLE`       | Yes      | --      | DynamoDB table for actively orchestrated matches (distributed lock, poll state) |
  | `MARQUEE_LEAGUE_ID`          | No       | --      | League ID to identify marquee matches for priority orchestration                |
  | `LA_DISMISSAL_DELAY_MINUTES` | No       | `5`     | Minutes to wait after user dismisses a LA before ending it server-side          |
</Accordion>

<Accordion title="APNs (Apple Push Notification service)">
  | Variable           | Required | Default      | Purpose                                             |
  | ------------------ | -------- | ------------ | --------------------------------------------------- |
  | `APNS_KEY_ID`      | Yes      | --           | The Key ID from your Apple Developer account        |
  | `APNS_TEAM_ID`     | Yes      | --           | Your Apple Developer Team ID                        |
  | `APNS_BUNDLE_ID`   | Yes      | --           | App bundle identifier (e.g., `com.sightscreen.app`) |
  | `APNS_KEY_PATH`    | Yes      | --           | Absolute path to the `.p8` private key file         |
  | `APNS_ENVIRONMENT` | No       | `production` | `production` or `sandbox`                           |

  <Note>
    For local development, set `APNS_ENVIRONMENT=sandbox` and use the sandbox APNs endpoint.
  </Note>
</Accordion>

<Accordion title="App version control">
  | Variable           | Required | Default | Purpose                                                             |
  | ------------------ | -------- | ------- | ------------------------------------------------------------------- |
  | `MIN_APP_VERSION`  | No       | `1.0.0` | Minimum supported app version. Clients below this are force-updated |
  | `STORE_URL`        | No       | --      | App Store URL shown in the force-update prompt                      |
  | `MAINTENANCE_MODE` | No       | `false` | Set to `true` to show maintenance screen on all clients             |
</Accordion>

<Accordion title="Job tuning">
  | Variable                      | Required | Default | Purpose                                                 |
  | ----------------------------- | -------- | ------- | ------------------------------------------------------- |
  | `DISABLE_LIVE_SCORE_JOB`      | No       | `false` | Disable the LiveScoreJob (ScorePoller for live matches) |
  | `DISABLE_FIXTURE_SYNC_JOB`    | No       | `false` | Disable the FixtureSyncJob                              |
  | `DISABLE_REPLAY_SCORE_JOB`    | No       | `false` | Disable the ReplayScoreJob (ScorePoller for replay)     |
  | `LIVE_SCORE_POLL_INTERVAL_MS` | No       | `2500`  | ScorePoller interval when matches are live              |
  | `IDLE_SCORE_POLL_INTERVAL_MS` | No       | `5000`  | ScorePoller interval when idle                          |
  | `FIXTURE_SYNC_INTERVAL_MS`    | No       | `60000` | FixtureSyncJob interval                                 |
</Accordion>

<Accordion title="Mock / Replay">
  | Variable                | Required | Default | Purpose                                                           |
  | ----------------------- | -------- | ------- | ----------------------------------------------------------------- |
  | `MOCK_SPORTMONKS_URL`   | No       | --      | URL of the mock SportMonks server. Setting this enables mock mode |
  | `MOCK_SPORTMONKS_TOKEN` | No       | --      | Auth token for the mock server                                    |

  <Warning>
    Never set mock mode variables in production. They redirect all SportMonks calls to the mock server.
  </Warning>
</Accordion>

<Accordion title="Stale (remove after Phase 9)">
  These variables are no longer used by the refactored backend but may still be referenced in infrastructure configs. Remove them after Phase 9 cleanup.

  | Variable                                | Previously used by                |
  | --------------------------------------- | --------------------------------- |
  | `DYNAMODB_ACTIVITY_SUBSCRIPTIONS_TABLE` | ActivityPushJob                   |
  | `DYNAMODB_PREMATCH_NOTIFICATIONS_TABLE` | PrematchNotificationJob           |
  | `MATCH_PROCESSING_STATE_TABLE`          | Legacy score processing           |
  | `STATE_HASHES_TABLE`                    | ActivityPushJob hash comparison   |
  | `DISPLAY_CACHE_TABLE`                   | Legacy display cache              |
  | `DISABLE_ACTIVITY_PUSH_JOB`             | ActivityPushJob (deleted)         |
  | `DISABLE_PREMATCH_NOTIFICATIONS`        | PrematchNotificationJob (deleted) |

  <Warning>
    Do not add these to new deployments. They exist only for backward compatibility during the Phase 9 transition.
  </Warning>
</Accordion>