Configuration reference

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

Quick reference

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

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

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

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

Admin

Variable	Required	Default	Purpose
`ADMIN_API_KEY`	Yes	—	Static API key for server-to-server admin access

Treat this like a password. Rotate it if compromised.

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

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)

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

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`

For local development, set APNS_ENVIRONMENT=sandbox and use the sandbox APNs endpoint.

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

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

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

Never set mock mode variables in production. They redirect all SportMonks calls to the mock server.

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)

Do not add these to new deployments. They exist only for backward compatibility during the Phase 9 transition.

Overview

Endpoints

Configuration reference

Quick reference

​Quick reference

Quick reference