From e4b211eb136aeac4c82fbf3613ecedf488d41415 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Sat, 2 May 2026 17:43:30 -0400 Subject: [PATCH] docs(flutter): replace flutter-create-default README Replaces the auto-generated `# minstrel\nMinstrel mobile client` stub from `flutter create` with a real setup + layout + CI + scope guide. Pointers to the spec, the M7 sequencing decision (web-first features ship before Flutter slice 2+), and the per-asset sync workflow. --- flutter_client/README.md | 86 +++++++++++++++++++++++++++++++++++----- 1 file changed, 75 insertions(+), 11 deletions(-) diff --git a/flutter_client/README.md b/flutter_client/README.md index 80c223f3..b511e3ab 100644 --- a/flutter_client/README.md +++ b/flutter_client/README.md @@ -1,17 +1,81 @@ -# minstrel +# Minstrel mobile client -Minstrel mobile client +Flutter (iOS + Android) sibling of the SvelteKit web SPA. v1 first +slice ships: scaffold, auth, library browse (home / artist / album), +likes, player with background audio + lock-screen controls. -## Getting Started +## Setup -This project is a starting point for a Flutter application. +```bash +cd flutter_client +flutter pub get +./tool/sync_shared.sh # copy tokens / error-copy / placeholders from ../web +dart run tool/gen_tokens.dart # regen lib/theme/tokens.dart from shared/fabledsword.tokens.json +flutter run +``` -A few resources to get you started if this is your first Flutter project: +`sync_shared.sh` is idempotent. CI runs it on every build; rerun locally +whenever `web/src/lib/styles/tokens.json`, +`web/src/lib/styles/error-copy.json`, or +`web/static/placeholders/album-fallback.svg` changes. -- [Learn Flutter](https://docs.flutter.dev/get-started/learn-flutter) -- [Write your first Flutter app](https://docs.flutter.dev/get-started/codelab) -- [Flutter learning resources](https://docs.flutter.dev/reference/learning-resources) +## Project layout -For help getting started with Flutter development, view the -[online documentation](https://docs.flutter.dev/), which offers tutorials, -samples, guidance on mobile development, and a full API reference. +See `docs/superpowers/specs/2026-05-02-flutter-mobile-foundation-design.md` +section 3. Briefly: + +- `lib/api/` — dio client, ApiError, error-copy loader, per-surface endpoints. +- `lib/auth/` — server URL screen, login screen, AuthController + secure storage. +- `lib/library/` — home, artist detail, album detail, providers, widgets. +- `lib/likes/` — LikeButton + optimistic toggle controller. +- `lib/player/` — audio handler, player provider, mini PlayerBar, NowPlaying. +- `lib/theme/` — FabledSword token Dart class (generated), ThemeExtension, ThemeData. +- `lib/shared/` — routing (go_router shell), version gate, connection error banner. + +`shared/fabledsword.tokens.json` and `assets/error-copy.json` are +synced from web/. Don't edit them directly — edit `web/src/lib/styles/` +and re-run `./tool/sync_shared.sh`. + +## Architecture + +- **State:** Riverpod 2 (`AsyncValue`, `AsyncNotifier`, family providers). +- **HTTP:** dio 5 with a Bearer-auth interceptor; 401 clears the session + and the router redirects to login. +- **Audio:** just_audio wrapped by audio_service for background + playback + lock-screen / notification controls. +- **Auth:** Bearer tokens in flutter_secure_storage. Server already + supports both cookie (web SPA) and Bearer (`internal/auth/session.go`). +- **Routing:** go_router with a ShellRoute so the PlayerBar persists + across navigation. Cold launch flow: no server-url → `/server-url`, + url set / no token → `/login`, token present → `/home`. + +## CI + +`.forgejo/workflows/flutter.yml` runs on push to dev/main, tag pushes, +PR to main, and manual dispatch — path-filtered to `flutter_client/**` +plus the shared web inputs. Steps: sync, analyze, test, build APK. +Debug APKs upload as artifacts; release APKs attach to the Forgejo +release on tag. + +## Versioning + +`pubspec.yaml` `version` mirrors the server tag (e.g. server `v0.1.0` +→ Flutter `0.1.0+1`). The server's `/healthz` returns +`min_client_version`; old clients show an Update Required modal and +refuse to operate. Bump `internal/server/version.go` `MinClientVersion` +when a server-side change requires a paired client update. + +## Distribution + +- **Android:** APK on the Forgejo release page. No Play Store for v1. +- **iOS:** TestFlight on tag (manual upload v1, automate later). + +## Out-of-scope for slice 1 + +Search, discover, requests, settings beyond server URL, admin, +listening history, playlists, offline cache (#357). Those land in +subsequent slices with their own brainstorm/spec/plan cycles. Per the +operator's M7 ordering decision (2026-05-02), slice 2+ pauses to ship +the missing web features first (#352 playlists, #362 theme toggle, +#363 queue UI, #364 listening history, etc.) before mirroring on +Flutter.