58 lines
3.3 KiB
Markdown
58 lines
3.3 KiB
Markdown
# 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.
|