Scrabble Scoresheet

Facts

Fact	Value
Status	dormant
Hosting platform	cloudflare
Repository	https://github.com/meta4m/scrabble-scoresheet
Tech stack	language: javascript, ui: vanilla-dom, styling: css, hosting: cloudflare-pages, persistence: localstorage
Tags	scrabble, scoresheet, tournament, offline-first, static-site
Last audited	2026-09-15
Upstream dependencies	None declared
Downstream dependencies	scorepad

Secrets manifest

Key names and metadata only. Encrypted records are available in this project’s vault below.

Key	Description	Environments	Required
`CLOUDFLARE_API_TOKEN`	Cloudflare API token (Pages: Edit) used by the GitHub Actions deploy workflow to publish the scrabble-scoresheet Pages project	production	Yes

Overview

Project Overview: Scrabble Scoresheet

1. Executive Summary

Mission: An online, browser-based Scrabble scoresheet for tournament play — each player keeps an independent sheet on their own device and exports a signed PDF as the official match record.
Target Audience: Scrabble tournament players tracking their own scores on a phone/tablet during live matches.
Primary Maintainer: The operator (meta4m) — internal project, all rights reserved.

2. Current Status & Roadmap

Lifecycle State: dormant — feature-complete, deployed, and stable. The last commits (2026-08-25) were documentation and deploy-trigger fixes, not feature work.
Roadmap hand-off: The README’s planned iterations (multi-device sync, match pairing, two-sheet reconciliation, tournament management, standings) are being realized in the successor project scorepad, which ships the identical source paper scoresheet (docs/scrabble_scoresheet.pdf, byte-identical) and implements this project’s data model server-side.

3. Core Capabilities

Tournament metadata + two-player score entry: direct keyboard entry, no spinners, live carried totals that never show partial sums, expandable rows (15 by default).
100-tile tracker: every physical tile individually toggleable; editable blanks with announced letter; consumed letter groups highlighted.
End-game rack adjustment: applies twice the opponent’s remaining rack value per tournament rules; automatic winner highlight and spread.
Saved sheets history: auto-saved to device localStorage, reopen/delete from a drawer; New sheet archives the previous one.
Print/PDF export: one-click A4 print stylesheet for signing and filing.
Zero backend: no accounts, no analytics, no third-party trackers; works offline once loaded (only Google Fonts is external).
Sibling projects in the operator’s scrabble suite: training app scrabbler and the D1-backed tournament manager scorepad.

4. Key References

Repository: meta4m/scrabble-scoresheet
Production URL: scrabble-scoresheet.pages.dev
Architecture Docs: architecture.md · Deployment Guide: deployment.md

Architecture

Architecture & System Design: Scrabble Scoresheet

1. System Topology

graph TD
    P1[Player 1 device] --> Pages[Cloudflare Pages<br/>static index.html / styles.css / app.js]
    P2[Player 2 device] --> Pages
    P1 --> LS1[(localStorage per device<br/>scrabble-scoresheets-v1)]
    P2 --> LS2[(localStorage per device<br/>scrabble-scoresheets-v1)]
    P1 -.->|Print / export| PDF[Signed PDF or paper match record]
    GH[GitHub Actions: push main] -->|wrangler pages deploy .| Pages

2. Core Components & Subsystems

index.html — static markup and structure (sheet form, tile tracker, final result, signature fields).
app.js (~11 KB) — all state, rendering, persistence, and interactions; direct DOM manipulation, no framework.
styles.css (~16 KB) — responsive layout plus a dedicated print stylesheet for A4 output.
docs/ — the source paper scoresheet (scrabble_scoresheet.pdf, “Scoresheet by Khalid Javed.docx”) the app digitizes; the same files seed scorepad’s docs.
CI — .github/workflows/deploy.yml: checkout → Node 20 → wrangler → pages deploy . on push to main or manual dispatch.

3. Data Flow & Storage Contracts

Primary storage: browser localStorage array key scrabble-scoresheets-v1; each record is { id (UUID), version: 2, createdAt/updatedAt, fields, rows, usedTiles, blankLetters }.
Versioning contract: version: 2 records; future versions must detect and migrate older records forward without data loss.
Server storage: none — Cloudflare Pages serves static files only and never receives scoresheet content; clearing site data or switching browsers starts a fresh history.

4. Architectural Decision Records (ADRs)

ADR-01: Zero-dependency vanilla JS, no build step

Context: A single-purpose tool that must load fast, work offline, and be auditable.
Decision: Static HTML + CSS + one app.js; any static file server can run it; no bundler.
Consequences: Nothing to build or update; features are limited to what hand-rolled DOM code can express — which the successor scorepad addresses by moving to React + Hono.

ADR-02: Two independent copies per match

Context: Tournament practice — each player keeps their own sheet to prevent single-typo official records and enable dispute resolution.
Decision: No shared state between devices; each copy is authoritative for its owner until cross-checked at round end.
Consequences: Privacy and offline simplicity, but no automatic reconciliation — the gap scorepad’s reconcile logic now fills.

ADR-03: localStorage-only persistence

Context: No accounts, no backend, no tracking by design.
Decision: All history stays on the device/browser profile.
Consequences: Data is lost if site data is cleared; multi-device sync requires the D1-backed successor, not an increment here.

ADR-04: Print-first official record

Context: Tournament rules want a signed, filed record.
Decision: A dedicated print stylesheet renders the sheet A4-clean; signatures happen on the printed/PDF copy.
Consequences: Signature fields are digital text on screen but the legal record is the printout; cryptographic signing remains future work.

Deployment

Deployment & Operational Runbook: Scrabble Scoresheet

1. Hosting & Environments

Environment	Platform	URL / Endpoint	Auto-Deploy Branch
Production	Cloudflare Pages	`https://scrabble-scoresheet.pages.dev`	`main` (GitHub Actions)
Local dev	Any static server	`http://localhost:4173`	N/A

2. Prerequisites & Toolchain

Any static file server (e.g. python3 -m http.server); no build step exists.
Node.js 20 + Wrangler (npm install) only for production-parity preview and deploys.

3. Local Development Setup

git clone https://github.com/meta4m/scrabble-scoresheet
cd scrabble-scoresheet
python3 -m http.server 4173      # open http://localhost:4173
# or, to match the production runtime:
npm install
npx wrangler pages dev .          # http://localhost:8788

4. Environment & Secrets Provisioning

Refer to spec.yml for declared secret keys.

Secret Injection: Retrieve ciphertext from 2Brain vault and decrypt locally into .env.local.
CI (GitHub Actions secrets): CLOUDFLARE_API_TOKEN (Pages: Edit token); CLOUDFLARE_ACCOUNT_ID is non-secret account config.
Application secrets: none — the app is static, has no backend, and stores nothing server-side.

5. Deployment Commands

# Automated path (primary): push to main triggers .github/workflows/deploy.yml
#   npx wrangler pages deploy . --project-name=scrabble-scoresheet --branch=main

# Manual deploy (package.json script):
npm run deploy    # wrangler pages deploy . --project-name=scrabble-scoresheet --commit-dirty=true

6. Verification & Health Checks

curl -f https://scrabble-scoresheet.pages.dev returns the sheet markup.
Smoke test: enter two scores → carried totals appear only when prior scores exist; mark tiles; enable end-game adjustment → winner/spread update; reload → sheet restored from localStorage.
Print preview (Ctrl/Cmd + P) renders the clean A4 layout.

7. Incident Response & Rollback

Rollback: redeploy the previous git revision — git checkout <good-sha> && npx wrangler pages deploy . --project-name=scrabble-scoresheet --branch=main (or re-run the workflow from the last good commit; each deployment also has an immutable URL in the Pages dashboard).
Data-loss reports: expected behavior for cleared site data / private windows — localStorage is the only store; no server-side recovery exists by design.
Feature requests (sync, pairing, reconciliation, standings): route to the active successor scorepad rather than restarting development here.

Project vault

Cloudflare Access authorization and your passphrase are required to retrieve and decrypt stored values.

Client-Side Encrypted Secret Vault

Zero-knowledge architecture. Secrets are encrypted client-side using Web Crypto AES-256-GCM before leaving this browser tab. Edge databases store only ciphertext, IV, and salt.

Vault Passphrase (PBKDF2-SHA256, 100,000 iterations):

Encrypted Records for `scrabble-scoresheet` (0)

Encrypted records have not been loaded.