Skip to main content

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

Try the live demo

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.
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 for the honest scope boundary. Nothing here is aspirational unless it says so.

​
Goals

​
High-level architecture

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

​
How to read this handbook

New to the project?

Start with System Architecture for the C4 view, then Frontend and Backend.

Want the 'why'?

Decisions records every major choice with alternatives and tradeoffs.

Debugging something?

The Engineering Log post-mortems every real production bug we hit.

Operating it?

DevOps, Testing, Observability, and Security cover running it.