checkpoint: focus seed 1.0.1 localized dev switch

2026-06-11 23:35:49 +08:00
parent c51abdfb73
commit d06dc35ee6
72 changed files with 6155 additions and 1390 deletions
@@ -0,0 +1,57 @@
+# Focus Seed 1.0.1 Architecture
+
+## Decision
+
+Keep the app offline-first and SDK-light. Flutter renders all product UI. `shared_preferences` remains the persistence adapter because the current dataset is one small versioned document and does not require relational queries, pagination, joins, or concurrent writers.
+
+Room is Android-only and would break the iOS-compatible boundary. MMKV adds a native dependency without solving a current bottleneck. If usage grows to hundreds of timeline records or indexed queries, migrate behind `FocusSeedStore` to an embedded cross-platform database without changing feature code.
+
+## Layers
+
+```text
+lib/src/
+  app/          Material theme, ambience integration, app lifecycle
+  application/  User commands and timer lifecycle controllers
+  core/         Pure date and ambience rules
+  data/         Persistence adapters
+  models/       Serializable state and derived domain models
+  features/     Today, Journey, Me, habits, reflection, shell
+  services/     Analytics and monetization interfaces/no-op adapters
+  widgets/      Reusable visual primitives
+```
+
+Rules:
+
+- Widgets render state and forward intent; they do not perform persistence.
+- `FocusSeedController` owns durable product commands and optimistic save rollback.
+- `FocusTimerController` owns only timer lifecycle and absolute-time restoration.
+- `FocusSeedStore` is the only durable app-state boundary.
+- External analytics, ads, billing, and remote configuration remain interfaces with no-op implementations until their SDK, consent, privacy, and policy work is approved together.
+
+## Navigation
+
+Use three top-level destinations:
+
+- Today: intention, timer, habits, reflection, and immediate daily progress.
+- Journey: daily lifecycle, recent sessions, reflections, and seven-day growth.
+- Me: appearance, privacy, import/export, and reset.
+
+Timer, habits, and reflection remain independent modules. They are actions inside the daily workflow instead of equal navigation destinations. This reduces context switching and preserves one primary task per screen. A future usage study may justify configurable shortcuts, but it should not restore five equal tabs by default.
+
+## Performance Contract
+
+- No network, location, background service, broadcast receiver, or foreground service.
+- One timer ticks only while a focus session is active and is disposed with the shell.
+- Background restoration derives remaining time from an absolute end timestamp; no background polling is used.
+- Day ambience schedules one callback at the next phase boundary and refreshes on resume.
+- Growth assets are fixed 640 px transparent PNGs and only transition when the domain stage changes.
+- Timer rebuilds stay inside `FocusSessionCard`; durable state changes rebuild the shell.
+- Long content uses lazy or bounded scrolling. Today shows four habits before offering the full manager.
+- Reduced motion replaces scale transitions with a crossfade.
+
+## Compatibility And Migration
+
+- Existing version 1 JSON loads through `AppState.fromJson` and is saved as version 2.
+- The package name, signing setup, version, permissions, and privacy posture are unchanged.
+- Android is the release target; architecture and dependencies remain compatible with a later iOS build.
+- Release artifacts must pass format, analyze, tests, manifest review, app bundle build, and emulator smoke testing.