labelle.games v2 — cloud-hosted OTA (custom companion + dashboard)

[apotema]

Status: v2 spec, deferred. v1 is live via Obtainium + GitHub Releases — see #178 for the shipped approach. This ticket tracks the upgrade path for when self-managed Obtainium subscriptions become a coordination bottleneck.

When to pick this up (triggers)

• Scale — more than ~20 active testers where manual Obtainium subscription management becomes a tax.
• External testers — paid or client-side testing programs that need a branded experience, not a generic 3rd-party Obtainium UI.
• Product metrics — need install counts per channel, version distribution, or crash reports pinned to a tester's device, which GitHub Releases doesn't surface cleanly.

Until one of the above is a real pain point, v1 (Obtainium) is the steady state.

v2 architecture

Cloud (labelle.games)

• API server — receives APK uploads, stores versions, manages testers/channels.
• Storage — S3-compatible blob store for APKs.
• Auth — GitHub OAuth for developers, email/link for testers.
• Web dashboard — project overview, tester management, version history.
• Endpoints:
  • POST /api/deploy — upload APK (from CLI).
  • GET /api/update/<project>/<channel> — companion app polls this.
  • GET /t/<project>/<channel> — tester onboarding web page.

CLI (labelle deploy upgrade)

• Reuses the existing labelle android deploy from v1 but swaps the upload target from GitHub Releases to labelle.games.
• Manages testers and channels server-side.

Companion app (Android) — #142

• Lightweight native app (~2MB), Kotlin or Flutter.
• Registers device with labelle.games.
• Polls for updates (or push via FCM).
• Silent install via Android PackageInstaller (one-time user opt-in).
• No game-specific code — works for any labelle project.

Child tickets

• labelle.games v2: Cloud API (upload, versioning, tester management) #140 — cloud API (Go/Rust/Node TBD; Postgres + S3/R2; GitHub OAuth).
• labelle.games v2: Android companion app (silent auto-update) #142 — Android companion app (silent auto-update).
• labelle.games v2: Web dashboard + tester onboarding page #143 — web dashboard + tester onboarding page.

Channels (v2)

• internal — default, immediate, no review.
• staging — pre-release testing.
• production — stable builds.

v2 roadmap

v2.0 — Cloud OTA

• Cloud API: upload, version check, tester management.
• CLI: labelle deploy switches to labelle.games backend (keeps GitHub Releases as a fallback).
• Companion app: auto-update, silent install.
• Web: tester onboarding link, basic dashboard.

v2.1 — Crash reporting

• Crash signal handler in labelle-engine (native crash → minidump).
• Upload to labelle.games with version + device info.
• Dashboard: crash list, stack traces, affected versions.

v3 — Platform expansion

• iOS support (via OTA manifest / TestFlight integration).
• Desktop builds (auto-updater).

Tech-stack decisions deferred until implementation starts

• API: Go / Rust / Node.
• Storage: S3 / R2 (Cloudflare) / GCS.
• Database: Postgres.
• Hosting: Fly.io / Railway / self-hosted.
• Companion app: Kotlin (minimal) or Flutter.

Prior art (examined during v1 pivot)

• Firebase App Distribution — good UX but Google lock-in.
• Expo Updates — JS-only.
• CodePush (Microsoft) — JS-only.
• TestFairy — commercial, broad platform support.
• Obtainium — picked for v1 (labelle.games v1 — Obtainium + GitHub Releases (shipped) #178).

Non-goals even at v2

• Play Store publishing (different workflow).
• A/B testing.
• Analytics beyond crash reporting + install counts.

Tracks #7 (Android support, closed).

[apotema]

Proposal: v1 pivot to Obtainium + GitHub Releases

Reconsidering the v1 scope after a design discussion. The current plan is a polished endpoint (custom companion app + centralized cloud + web dashboard), but it's weeks of work before a single tester sees an update. The pivot below ships the OTA loop in days and defers the polished pieces to v2.

v1 architecture

Zero new infrastructure. GitHub Releases is a first-class Obtainium source — Obtainium already knows how to poll github.com/<org>/<game>/releases and detect new APK assets.

Flow:

1. CI builds the Android APK on tag push (already exists per Android: CI pipeline to build APK + publish to GitHub Releases #138).
2. `labelle deploy android` wraps `labelle build android` + `gh release create`.
3. Testers install Obtainium once.
4. Tester pastes `https://github.com//` into Obtainium — it auto-detects GitHub and finds the latest release.
5. New versions show up in Obtainium's Apps list; one tap to install.

What this collapses from the original plan

• labelle.games v2: Cloud API (upload, versioning, tester management) #140 (cloud API) → deferred to v2. GitHub Releases is the API for v1.
• labelle deploy android: build + GitHub Releases upload (v1) #141 (labelle deploy) → rescoped to the minimal wrapper: `build + gh release create`. No auth beyond `gh auth login`. Retained as the v1 ticket.
• labelle.games v2: Android companion app (silent auto-update) #142 (companion app + silent auto-update) → deferred to v2. Strictly better UX, but Obtainium's tap-to-install is sufficient for internal testing and gets us working in days instead of weeks.
• labelle.games v2: Web dashboard + tester onboarding page #143 (web dashboard + onboarding page) → deferred to v2. Share the GitHub repo URL directly; no custom onboarding page.

Why the earlier "no Obtainium" decision was premature

The original epic body positions Obtainium as a worse UX than the custom companion. That comparison is valid for a finished product but ignores the time-to-first-tester cost. For v1 — "get a tablet auto-updating from a dev's laptop" — Obtainium is the lowest-effort path that works end-to-end.

Tradeoffs accepted for v1

• Channels: GitHub's pre-release flag covers `stable` vs `preview`. A third channel (e.g. `internal`) can use separate repos or tag prefixes if needed.
• Tester management: testers self-manage subscriptions inside Obtainium; revocation means making the repo private. For internal-only testing, invite them to the private repo and distribute a PAT.
• Branded UX: testers see Obtainium's UI, not a labelle-branded one.

v2 triggers (when to pick the custom path back up)

• Growth past ~20 testers where self-management in Obtainium becomes a coordination tax.
• External/client testing where a branded experience matters.
• Product metrics requirement (install counts per channel, version distribution) that GitHub Releases doesn't expose cleanly.

Acceptance for v1

A developer runs `labelle deploy android`, a tester's Obtainium-subscribed tablet receives the new version within minutes, no extra human steps.

---

If this reads right, I'll rescope #141 accordingly and drop a deferred-to-v2 comment on #140 / #142 / #143.