developer/galaxy-game
1
1
Fork 0
Code Issues Pull Requests Actions Packages Releases Wiki Activity

docs(ui): finalize MVP plan structure and de-archaeologize topic docs

Browse Source 
MVP web client (Phases 1-30) is complete; reorganize planning + living docs around that.

- PLAN.md kept as the staged MVP record (1-30) with a status block + pointers; removed the 31-36 stages, regression scenarios, and deferred-TODO section (moved out); fixed a stale cross-machine plan path.

- ui/PLAN-finalize.md (new): active web-finalization plan in 8 stages (visual system, a11y, i18n, error UX, PWA, build hygiene, docs, owner manual-QA loop); absorbs former Phases 33 and 35.

- ui/ROADMAP.md (new): post-MVP (Wails, Capacitor, realistic projection, acceptance + regression scenarios) and triaged deferred follow-ups.

- ui/docs/README.md (new): grouped topic-doc index.

- De-archaeologized all 20 ui/docs topic docs + ui/README.md + ui/core/README.md: stripped Phase-N build history, rewritten as current-state; deferred work now points at ROADMAP.md / PLAN-finalize.md. Docs-only; no code change.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ilia Denisov
2026-05-21 23:17:51 +02:00
parent 51865b8cf4
commit a89048f6c5
26 changed files with 836 additions and 929 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ui/README.md
+41 -53
View File
@@ -14,24 +14,22 @@ boundary on every platform.
The legacy Fyne client under `client/` is reference-only.
Nothing in `ui/` imports from it.
The full staged implementation plan lives in `PLAN.md`. The
strategic rationale (why Svelte, why PixiJS, why Go-as-WASM, why
The strategic rationale (why Svelte, why PixiJS, why Go-as-WASM, why
Wails+Capacitor) lives outside the repo at
`~/.claude/plans/buzzing-questing-fountain.md`. This README is a
quick orientation; deeper per-phase design notes earn their place
under `ui/docs/` as they are introduced.
quick orientation; deeper design notes live under `ui/docs/`.
## Targets
| Target | Wrapper | Toolchain | Phase |
| --------------- | ---------------- | ----------------------- | -------- |
| web | browser tab | Vite + WASM | 5+ |
| web-mobile | mobile browser | Vite + WASM | 5+ |
| desktop (mac) | Wails v2 | Go + Wails CLI | 31 |
| desktop (win) | Wails v2 | Go + Wails CLI | 31 |
| desktop (linux) | Wails v2 | Go + Wails CLI | 31 |
| iOS | Capacitor | gomobile + Xcode | 32+ |
| Android | Capacitor | gomobile + Gradle | 32+ |
| Target | Wrapper | Toolchain | Status |
| --------------- | ---------------- | ----------------------- | ------------------------------ |
| web | browser tab | Vite + WASM | implemented |
| web-mobile | mobile browser | Vite + WASM | implemented |
| desktop (mac) | Wails v2 | Go + Wails CLI | planned (see ROADMAP.md) |
| desktop (win) | Wails v2 | Go + Wails CLI | planned (see ROADMAP.md) |
| desktop (linux) | Wails v2 | Go + Wails CLI | planned (see ROADMAP.md) |
| iOS | Capacitor | gomobile + Xcode | planned (see ROADMAP.md) |
| Android | Capacitor | gomobile + Gradle | planned (see ROADMAP.md) |
## Layered architecture
@@ -58,7 +56,9 @@ under `ui/docs/` as they are introduced.
```text
ui/
├── PLAN.md staged implementation plan (Phases 1-36)
├── PLAN.md staged implementation plan
├── ROADMAP.md planned desktop / mobile / multi-turn features
├── PLAN-finalize.md PWA, accessibility, localisation, error UX
├── Makefile wasm / ts-protos / web / mobile / desktop targets
├── README.md this file
├── buf.gen.yaml local-plugin TS Protobuf-ES generator
@@ -71,6 +71,9 @@ ui/
│ └── wasm-toolchain.md TinyGo build, JSDOM loading, bundle budget
├── core/ ui/core Go module (canonical bytes, keypair)
├── wasm/ TinyGo entry point exposing Core to JS
├── mobile-bridge/ gomobile bindings (planned — see ROADMAP.md)
├── desktop/ Wails project (planned — see ROADMAP.md)
├── mobile/ Capacitor project (planned — see ROADMAP.md)
└── frontend/ SvelteKit / Vite source
├── src/api/ GalaxyClient + typed Connect client + auth + session
├── src/lib/ env config, session store, revocation watcher
@@ -98,40 +101,23 @@ Linked topic docs:
- [`docs/testing.md`](docs/testing.md) — Tier 1 per-PR + Tier 2
release test tiers.
```text
ui/
├── README.md this file
├── PLAN.md staged implementation plan
├── Makefile cross-target build placeholders
├── pnpm-workspace.yaml pnpm workspace root
├── .gitignore
├── docs/ per-phase topic docs (added per phase)
├── frontend/ TS + Svelte source, shared across targets
├── core/ Go module ui/core (Phase 3+)
├── wasm/ TinyGo entry point for core.wasm (Phase 5)
├── mobile-bridge/ gomobile bindings (Phase 32+)
├── desktop/ Wails project (Phase 31)
├── mobile/ Capacitor project (Phase 32+)
└── web/ static deploy assets (Phase 30+)
```
## Build pipeline
Every cross-target build flows through `make` at this level. All
named targets are placeholders until the named phase lands; running
`make` with no arguments prints the current placeholder map.
Every cross-target build flows through `make` at this level.
Native targets are placeholders until their platform work lands;
running `make` with no arguments prints the current placeholder map.
```text
make web Vite production build Phase 5+
make wasm TinyGo → core.wasm Phase 5
make ts-protos Connect-ES + Protobuf-ES gen Phase 5
make fbs-ts FlatBuffers TS bindings via flatc Phase 8
make gomobile gomobile bind → ios + android Phase 32+
make desktop-mac Wails build for darwin Phase 31
make desktop-win Wails build for windows Phase 31
make desktop-linux Wails build for linux Phase 31
make ios Capacitor + xcodebuild Phase 32+
make android Capacitor + gradle Phase 32+
make web Vite production build
make wasm TinyGo → core.wasm
make ts-protos Connect-ES + Protobuf-ES gen
make fbs-ts FlatBuffers TS bindings via flatc
make gomobile gomobile bind → ios + android (planned — see ROADMAP.md)
make desktop-mac Wails build for darwin (planned — see ROADMAP.md)
make desktop-win Wails build for windows (planned — see ROADMAP.md)
make desktop-linux Wails build for linux (planned — see ROADMAP.md)
make ios Capacitor + xcodebuild (planned — see ROADMAP.md)
make android Capacitor + gradle (planned — see ROADMAP.md)
make all every target above
```
@@ -159,18 +145,20 @@ hostnames — use the long-lived dev environment at
[`../tools/dev-deploy/`](../tools/dev-deploy/README.md). It is
redeployed by Gitea Actions on every merge into `development`.
## Per-phase docs
## Topic docs
Topic docs live under `ui/docs/` and are added per phase as they're
needed (testing tiers, WASM toolchain, navigation shell, renderer
internals, sync protocol, auth flow, and so on). The staged plan in
`PLAN.md` names the topic doc each phase produces.
Topic docs live under `ui/docs/` (testing tiers, WASM toolchain,
navigation shell, renderer internals, sync protocol, auth flow, and
so on).
## Cross-references
- [`PLAN.md`](./PLAN.md) — staged implementation plan with goals,
artifacts, dependencies, acceptance criteria, and targeted tests
per phase.
- [`PLAN.md`](./PLAN.md) — staged implementation plan (historical
record of completed work).
- [`ROADMAP.md`](./ROADMAP.md) — planned desktop / mobile / multi-turn
projection features.
- [`PLAN-finalize.md`](./PLAN-finalize.md) — PWA, accessibility,
localisation, error UX finalization work.
- [`../docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md) — platform
architecture and the transport security model (§15) the client
envelope contract derives from.
@@ -178,4 +166,4 @@ internals, sync protocol, auth flow, and so on). The staged plan in
stories that drive the UI flows.
- [`../docs/TESTING.md`](../docs/TESTING.md) — project-wide testing
layers; UI-specific test tiers (Vitest, Playwright) live in
`ui/docs/testing.md` from Phase 2 onward.
`ui/docs/testing.md`.