docs(android): add Android app design plan #6

wtclaude · 2026-07-19T08:15:08Z

wtclaude commented

2026-07-19 08:15:08 +00:00

What & why

Adds docs/android/PLAN.md — the design contract for the new RunicGateway/Android-app repo. Planning only; no app code exists yet. This gives the org a single, reviewable source of truth before implementation, and records the cross-repo (website) prerequisites the app depends on.

The app, in short: a native Kotlin + Jetpack Compose client of the website v1 API. It surfaces public content + public shard widgets (including the SSE live stream), native username/password + TOTP login, player self-service, and a player's own shard/game data. It excludes every admin/management console (hero editor, auth/provider admin, Discord bot, shard/uo-link ops).

Key decisions captured in the plan:

Stay on v1 — every addition (role-agnostic /auth/me/* self surface, push endpoints) is additive, so no v2 is warranted.
Registration / invite / password-reset / SSO are website-handled hand-offs (Chrome Custom Tab), not native screens — the app's only native auth is username/password + TOTP. This keeps all credential/OAuth flows in one audited place.
Password reset is built on the backend + web front end first, as a prerequisite, not app scope.
Single shard per install; minSdk 29; no telemetry and no offline cache in v1; text-only game data (pretty paperdoll is future); strings externalized from day one.
Push via a self-hosted ntfy / UnifiedPush service (added to the website compose, fully automated) using content-free tickles so the relay stays untrusted and every existing security rule (allowlist split, owner-keyed personal events) holds.
Build & CI on Gitea Actions ubuntu:latest, with a signed-APK Gitea release for v1 and Google Play later.

The plan enumerates the website-side work to land first (§8): the /auth/me/* self surface, the password-reset feature, the ntfy service + push endpoints, and version/health + branding confirmations.

How it was tested

Documentation only — no code. The plan was cross-checked against the current website/server API surface (routers, session.middleware/token.js bearer support, roles, mobile auth) to keep every endpoint reference and the "already verified / still to build" split accurate.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

AI tools were used. Tool(s): Claude Code (Opus 4.8). I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a Co-Authored-By trailer.

License

I agree that my contribution is licensed under this project's license (GNU GPL v3.0 or later), and I have the right to contribute it.

🤖 Generated with Claude Code

## What & why Adds `docs/android/PLAN.md` — the design contract for the new `RunicGateway/Android-app` repo. **Planning only; no app code exists yet.** This gives the org a single, reviewable source of truth before implementation, and records the cross-repo (website) prerequisites the app depends on. **The app, in short:** a native **Kotlin + Jetpack Compose** client of the website **v1** API. It surfaces public content + public shard widgets (including the SSE live stream), native username/password + TOTP login, player self-service, and a player's *own* shard/game data. It excludes every admin/management console (hero editor, auth/provider admin, Discord bot, shard/uo-link ops). **Key decisions captured in the plan:** - **Stay on v1** — every addition (role-agnostic `/auth/me/*` self surface, push endpoints) is *additive*, so no v2 is warranted. - **Registration / invite / password-reset / SSO are website-handled** hand-offs (Chrome Custom Tab), not native screens — the app's only native auth is username/password + TOTP. This keeps all credential/OAuth flows in one audited place. - **Password reset is built on the backend + web front end first**, as a prerequisite, not app scope. - Single shard per install; **minSdk 29**; **no telemetry** and **no offline cache** in v1; **text-only** game data (pretty paperdoll is future); strings **externalized from day one**. - **Push** via a **self-hosted ntfy / UnifiedPush** service (added to the website compose, fully automated) using **content-free tickles** so the relay stays untrusted and every existing security rule (allowlist split, owner-keyed personal events) holds. - **Build & CI** on Gitea Actions `ubuntu:latest`, with a signed-APK Gitea release for v1 and Google Play later. The plan enumerates the website-side work to land first (§8): the `/auth/me/*` self surface, the password-reset feature, the ntfy service + push endpoints, and version/health + branding confirmations. ## How it was tested Documentation only — no code. The plan was cross-checked against the current `website/server` API surface (routers, `session.middleware`/`token.js` bearer support, roles, mobile auth) to keep every endpoint reference and the "already verified / still to build" split accurate. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally.  - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [x] AI tools were used. Tool(s): `Claude Code (Opus 4.8)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

wtclaude added 1 commit 2026-07-19 08:15:09 +00:00

docs(android): add Android app design plan 8963269ff0

Add docs/android/PLAN.md — the design contract for the RunicGateway/Android-app
repo (planning only, no app code yet).

Scope: native Kotlin + Jetpack Compose client of the website v1 API. Public
content + public shard widgets (incl. SSE), native username/password + TOTP
login, player self-service via a new role-agnostic /auth/me/* surface, and a
player's own shard/game data. Excludes every admin/management console (hero
editor, auth/provider admin, Discord bot, shard/uo-link ops).

Key decisions captured: stay on v1 (all additions are additive, no v2);
registration/invite/reset/SSO are website-handled hand-offs, not native screens;
password reset is built on the backend + web front end first; single shard per
install; minSdk 29; no telemetry and no offline cache in v1; text-only game data
(paperdoll is future); strings externalized from day one; push via a self-hosted
ntfy/UnifiedPush service with content-free tickles that keep the relay untrusted;
Gitea Actions build on ubuntu:latest with a signed-APK release.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech approved these changes 2026-07-19 08:17:38 +00:00

whitlocktech merged commit 033292504e into main

2026-07-19 08:17:44 +00:00

whitlocktech deleted branch docs/android-app-plan

2026-07-19 08:17:44 +00:00

whitlocktech referenced this issue from a commit

2026-07-19 08:17:45 +00:00

Merge pull request 'docs(android): add Android app design plan' (#6) from docs/android-app-plan into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#6