Skip to content

Technical

Architecture, code, and deployment for S.A.G.E. If you want to know what a feature does rather than how it's built, its counterpart lives in Features and is linked from the bottom of each page here. To run an event, start with the Usage guide.

Start here

  • Architecture — the three repos, the data flow between them, and how a score gets from a spreadsheet to a phone.

Backend (sage-tools-api)

  • Sync pipeline — Sheets → GitHub, the runtime-fetched event registry, the live-delivery path (the live push Worker, the GitHub archive and polling fallback, the operator switch), and how score entry writes a score and publishes it.
  • API — the one REST surface, /v3, its conventions, errors and routes, and the frozen legacy and /v1 URLs it replaces for new clients.
  • Scoresheet pipeline — CSV → Handlebars → Chromium → merged PDF.
  • Auth — the operator sign-in, how it interacts with the legacy shared-secret path, and the desk and scorer tokens.
  • Deployment — Cloud Run setup, the version/changelog convention, environment variables.
  • Event attendance — src/attendance/: the roster, the ATTENDANCE tab, desk tokens, and the /v3 routes and their frozen /v1 twins. It is part of the API, not Apps Script. Also the shared client block, and Pickle for Sight's own attendance.gs.

Bound Apps Script (in sage-tools-api, but not the API)

The three files live in sage-tools-api/apps-script/ for versioning, run inside a Google Sheet, and ship by being pasted into that sheet's own script project — changing any of them is not a deploy.

  • Dual Meet Sheet Generator — builds a dual meet's category tabs from a Tournament Calculator CSV.
  • Named Function library — the 23 workbook-level LAMBDA definitions those generated formulas call. Not Apps Script: they live in the workbook itself, under Data → Named functions.
  • Standard Tournament Generator — builds one facility-day's standard-tournament workbook from a calculator CSV.
  • The sync trigger (sheets-sync.gs) is covered in Sync pipeline.

Frontend (sage-match-control.github.io)

  • Site engine — the shared modules under lib/v1/ every event page and Control Center import: layout, dependency rules, the versioning rule, the model the views read, the extension points, the theme contract and the comparison harness.
  • Control Center — the single-page operator console: config resolution, theming, the tabs (including the Attendance tab around the shared attendance client, score entry and its shared dialog, the Awards tab's podium derivation, bye/walkover handling, and Canvas 2D image export).
  • Scorer page — the per-event page a scorer link opens: its template, start-up checks, token storage and data loading.
  • Schedule board — the venue wall display.
  • Tournament Calculator — the dual-meet math fixes and its PWA (installable, offline) setup.
  • Bracket Generator — the one-palette-source arrangement that keeps the canvas export in step with the page.

Data (event-data)

Operations

  • Adding a new event — the developer's mechanics for Usage steps 4–6: registering the event, instantiating a template, connecting the workbooks, the QR panel.