> ## Documentation Index
> Fetch the complete documentation index at: https://sportzdocs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sportz Engineering Handbook

> Architecture, decisions, and operations for the Sportz real-time match platform.

## What Sportz is

Sportz is a **real-time match broadcast platform**. It ingests live match data (scores and ball-by-ball commentary) and delivers it to connected clients with sub-second latency over WebSockets. A football goal, a cricket wicket, a basketball three-pointer: the moment it's recorded via the API, every subscribed client sees it without refreshing.

> [card] [Try the live demo](https://sportz-ui.vercel.app)
>
> See it running: live scores and commentary, streamed in real time.

It is two deployed applications plus a managed database:

* **`sportz`**: the backend API: Express + WebSocket server, Drizzle ORM over Neon Postgres, protected by Arcjet.
* **`sportz-ui`**: the frontend: Next.js (App Router) client app with React Query, Framer Motion, and a yellow-forward design system.
* **Neon**: serverless Postgres, with ephemeral branches for local dev and a pooled connection in production.

> [!NOTE]
>
> This handbook documents the system **as it actually exists today**. Where a capability is planned but not yet built, it is marked explicitly, see [Project Status](https://sportzdocs.mintlify.site/project-status.md) for the honest scope boundary. Nothing here is aspirational unless it says so.

## Goals

| Dimension | Goal |
| - | - |
| **Product** | Let a viewer follow a live match (scores + commentary) updating in real time, across football, cricket, and basketball. |
| **Technical** | Single HTTP server hosting both REST and WebSocket; type-safe end to end; deployable as one container. |
| **Operational** | Reproducible local dev (Docker + Neon Local), automated tests in CI, one-command deploy. |
| **Quality** | Every architectural choice is recorded with its tradeoffs (see [Decisions](https://sportzdocs.mintlify.site/decisions.md)); every production bug is post-mortemed (see [Issues](https://sportzdocs.mintlify.site/issues.md)). |

## High-level architecture

```mermaid theme={null}
flowchart LR
  subgraph client["sportz-ui (Next.js)"]
    UI["Match grid + Commentary panel"]
  end
  subgraph api["sportz (Express + ws)"]
    REST["REST routes\n/matches, /commentary"]
    WS["WebSocket server\n/ws"]
  end
  DB[("Neon Postgres")]

  UI -- "REST: fetch matches/commentary" --> REST
  UI <-- "WebSocket: live events" --> WS
  REST -- "Drizzle ORM" --> DB
  REST -- "broadcast()" --> WS
```

When a match or commentary event is created via REST, the route writes it to Postgres and then calls a broadcast function that pushes it out over the WebSocket layer, so the client that's watching sees it instantly, and so does every other connected client.

## Platform capabilities matrix

| Capability | Status | Where it's documented |
| - | - | - |
| REST API (matches, commentary) | ✅ Built | [Backend](https://sportzdocs.mintlify.site/architecture/backend.md), [API Reference](https://sportzdocs.mintlify.site/reference/api.md) |
| WebSocket live broadcast | ✅ Built | [Real-Time Deep Dive](https://sportzdocs.mintlify.site/architecture/realtime.md) |
| Live score updates (broadcast to all) | ✅ Built | [ADR-010](https://sportzdocs.mintlify.site/decisions.md), [API Reference](https://sportzdocs.mintlify.site/reference/api.md) |
| Demo mode (in-process multi-sport simulator) | ✅ Built | [ADR-011](https://sportzdocs.mintlify.site/decisions.md) |
| Match status derivation (scheduled/live/finished) | ✅ Built | [Backend](https://sportzdocs.mintlify.site/architecture/backend.md) |
| Input validation (Zod) | ✅ Built | [Security](https://sportzdocs.mintlify.site/operations/security.md) |
| Rate limiting + bot protection (Arcjet) | ✅ Built | [Security](https://sportzdocs.mintlify.site/operations/security.md) |
| Backend tests (Vitest, 95 tests) | ✅ Built | [Testing](https://sportzdocs.mintlify.site/operations/testing.md) |
| Frontend E2E + a11y (Playwright) | ✅ Built | [Testing](https://sportzdocs.mintlify.site/operations/testing.md) |
| Deployed smoke test (live stack) | ✅ Built | [Testing](https://sportzdocs.mintlify.site/operations/testing.md) |
| CI/CD: backend (Actions) + frontend (Actions + Vercel) | ✅ Built | [DevOps](https://sportzdocs.mintlify.site/operations/devops.md) |
| Branch protection (CI gates production) | ✅ Built | [DevOps](https://sportzdocs.mintlify.site/operations/devops.md) |
| Containerized deploy (backend → Render, frontend → Vercel) | ✅ Built | [DevOps](https://sportzdocs.mintlify.site/operations/devops.md) |
| Frontend observability (New Relic, PostHog) | ✅ Built | [Observability](https://sportzdocs.mintlify.site/operations/observability.md) |
| Backend observability (New Relic APM, PostHog) | ✅ Built | [Observability](https://sportzdocs.mintlify.site/operations/observability.md) |
| Authentication / authorization | ❌ Not built | [Project Status](https://sportzdocs.mintlify.site/project-status.md) |
| Caching layer (Redis) / queues | ❌ Not built | [Project Status](https://sportzdocs.mintlify.site/project-status.md) |

## How to read this handbook

> [card] [New to the project?](https://sportzdocs.mintlify.site/architecture/system.md)
>
> Start with System Architecture for the C4 view, then Frontend and Backend.

> [card] [Want the 'why'?](https://sportzdocs.mintlify.site/decisions.md)
>
> Decisions records every major choice with alternatives and tradeoffs.

> [card] [Debugging something?](https://sportzdocs.mintlify.site/issues.md)
>
> The Engineering Log post-mortems every real production bug we hit.

> [card] [Operating it?](https://sportzdocs.mintlify.site/operations/devops.md)
>
> DevOps, Testing, Observability, and Security cover running it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.