gp/docs/architecture/v1.0.1-architecture.md

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

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.