> ## 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.

# Overview

> What is Sightscreen — an event-driven cricket live-scoring platform with backend API, iOS app, and Pavilion admin app.

## What is Sightscreen?

Sightscreen is a real-time cricket live-scoring platform. It pulls fixture and scoring data from external APIs, detects match events through an event-driven pipeline, builds display state, and pushes updates to users via an iOS app with Live Activities and push notifications.

The platform has three main surfaces:

* **iOS App** — SwiftUI app with Live Activities (ActivityKit) for ball-by-ball match tracking
* **Backend API** — Express/TypeScript service running on Node.js, built around an event-driven architecture for real-time match processing and APNs delivery
* **Pavilion** — iOS admin app for managing fixtures, leagues, and monitoring system health

## Tech stack

| Layer         | Technology                                   |
| ------------- | -------------------------------------------- |
| iOS           | Swift, SwiftUI, ActivityKit, WidgetKit       |
| Backend       | Node.js, Express, TypeScript                 |
| Admin         | iOS (Pavilion)                               |
| Database      | AWS DynamoDB                                 |
| Auth          | AWS Cognito (JWT)                            |
| External data | SportMonks Cricket API                       |
| Push          | Apple APNs (notifications + Live Activities) |
| Resilience    | Cockatiel (timeout, circuit breaker, retry)  |

## Architecture at a glance

The backend follows an **event-driven architecture** (LA v2). Instead of monolithic polling jobs that detect changes and push updates in one pass, the system separates concerns into a pipeline:

```
Pollers → MatchEventBus → Detectors → Filters → LACoordinator → APNs
```

* **ScorePoller / MarqueePoller** fetch data from SportMonks
* **MatchEventBus** routes raw data through the event detection pipeline
* **Tier0 / Tier1 detectors** classify events by importance
* **CooldownFilter / StalenessFilter** suppress noise
* **LACoordinator** coordinates APNs delivery with priority management
* **MatchOrchestrator** manages the full match lifecycle

## What this docs site is for

This is an **internal living architecture map**. It exists so any developer working on Sightscreen can:

* Quickly understand how the system fits together
* Find which service owns a given responsibility
* Trace data flow from external APIs to the user's screen
* Debug production issues without reading every source file first

<Note>
  This is not public documentation. It is a working reference that should be updated as the system evolves.
</Note>

## Where to start

<Cards>
  <Card title="System context" icon="diagram-project" href="/system-map/system-context">
    How all systems and external services connect
  </Card>

  <Card title="Layer architecture" icon="layer-group" href="/system-map/layers">
    How the backend is structured internally
  </Card>

  <Card title="Data model" icon="database" href="/system-map/data-model">
    All DynamoDB tables, keys, GSIs, and access patterns
  </Card>
</Cards>