Skip to content

Architecture

OPEN is split into a few repositories, each with one job. The backend stores the match ledger and will serve ratings. The engine holds the rating math. The rating spec defines that math in words. The frontend is the public app.

How the pieces fit together

   Players and organizers           Partners (apps, league platforms,
   in a browser                     clubs, tournaments)
          |                                   |
          v                                   v
 +------------------+              +----------------------+
 | Frontend web app |              | Partner integrations |
 | (frontend repo,  |              | OAuth2 tokens        |
 |  planned)        |              | (API planned)        |
 +------------------+              +----------------------+
          |  /api/v1/ and /_allauth/          |  /oauth/ and /api/v1/
          v                                   v
 +-----------------------------------------------------------+
 | Backend (Django)                                          |
 |  API at /api/v1/   accounts at /_allauth/   admin         |
 |  match ledger, confirmation workflow, audit log           |
 |  Celery workers and beat: default, ratings, email,        |
 |  webhooks queues                                          |
 |                                                           |
 |  +---------------------------+                            |
 |  | Engine (Python package),  |  imported in-process,      |
 |  | replay and live updates   |  planned                   |
 |  +---------------------------+                            |
 +-----------------------------------------------------------+
       |                  |                   |
       v                  v                   v
   Postgres         Valkey (cache        Email provider
   (ledger and      and Celery           (Resend)
   all records)     broker)

 Rating spec (rating-spec repository): the official definition
 of the math. The engine implements a spec version, identified by
 its config version and config fingerprint.

 openpb.org: a static teaser from the frontend repository on
 GitHub Pages. It is live and calls no backend.

 Status page (status.openpb.org, planned): checks the backend
 from outside, so it stays up when the backend is down.

Frontend

Repository: openpickleball/frontend.

  • site/ is a static teaser served at openpb.org by GitHub Pages. It is live.
  • app/ is the full web app, a SvelteKit single-page app built as an installable PWA. It is in development and not deployed. It talks to the backend's API at /api/v1/ and to the account endpoints at /_allauth/, and generates its API types from their OpenAPI documents.

Backend

Repository: openpickleball/backend.

A Django project that holds every record and will serve ratings.

  • One API at /api/v1/, with an OpenAPI document and one error format (ADR 0005). Records are named by OPEN Codes, never row ids (ADR 0008).
  • Accounts use headless sign-up, login, email verification, and password reset at /_allauth/ (ADR 0014). Players must be 13 or older (ADR 0017).
  • Partners get OAuth2 clients. The token and revoke endpoints exist at /oauth/. No API operation accepts a partner token yet (ADR 0010).
  • The match ledger is append-only. See How a match becomes a rating.
  • The audit log records every sensitive action, and the database refuses to change or delete its rows (ADR 0007).
  • Background work runs in Celery on four queues: default, ratings, email, and webhooks (ADR 0006). Email goes through an outbox and the email queue (ADR 0016).
  • Hosting on DigitalOcean App Platform is planned.

What the API serves today: health checks, the signed-in account, a player's own match submission, confirm and dispute, and a player's match history. Rating endpoints, partner endpoints, and organizer upload tools are planned.

Engine

Repository: openpickleball/engine.

The reference rating engine, a Python package (openpickleball-engine, imported as open_engine) with no runtime dependencies. It records matches live and rebuilds ratings with a deterministic replay of the ledger. The backend will import it in-process, so the API, scheduled replays, and backtests all run the same code (ADR 0001). The backend does not depend on it yet. When it does, the engine is pinned to a release tag, and its output stays labeled as demonstration ratings.

Rating spec

Repository: openpickleball/rating-spec.

The official definition of how an OPEN rating is calculated: the inputs, the math, the parameters, and how reliability is reported. Changes go through a public proposal (an RFC), and only the governing board changes the official version. Each published version records the config version and config fingerprint that implement it, so a published rating can be reproduced from the ledger. No version is published yet.

Status page

Planned at status.openpb.org (backend#139). It will check the backend from outside and report whether ratings are fresh (backend#140).

This site

openpickleball/developers is a static MkDocs site on GitHub Pages. It calls no OPEN service and loads nothing from another host, so it stays up when the backend is down.