gp/launch/architecture.md

Focus Seed Architecture

Status: refactored from single-file prototype into modular Flutter structure.

Directory Layout

lib/
  main.dart
  src/
    app/
      focus_seed_app.dart
      app_theme.dart
    core/
      date_keys.dart
      iterable_extensions.dart
      json_utils.dart
    data/
      focus_seed_store.dart
    models/
      app_state.dart
      focus_session.dart
      habit.dart
      mood.dart
      reflection_entry.dart
    services/
      analytics_provider.dart
      monetization_provider.dart
    features/
      shell/
        focus_seed_home.dart
      home/
        home_screen.dart
      timer/
        timer_screen.dart
      habits/
        habits_screen.dart
      reflection/
        reflection_screen.dart
      settings/
        settings_screen.dart
    widgets/
      app_scaffold.dart
      dialogs.dart
      empty_state.dart
      habit_row.dart
      inline_editable_text.dart
      loading_view.dart
      metric_tile.dart
      section_label.dart
      seed_card.dart
      settings_tile.dart
      weekly_progress.dart

Responsibility Boundaries

• main.dart: process entry only.
• src/app: app shell and theme.
• src/models: serializable domain objects.
• src/data: persistence boundary using shared_preferences.
• src/services: no-op interfaces for analytics and monetization.
• src/features/shell: state orchestration and feature routing.
• src/features/*: screen-level UI and user flows.
• src/widgets: reusable UI components and dialogs.
• src/core: framework-light utilities.

Current Design Decisions

• No real ad SDK in V1.
• No real billing SDK in V1.
• No analytics SDK in V1.
• No network dependency.
• JSON import/export uses copy/paste to avoid file permissions.
• Shell owns state until a future state-management package is justified.

Upgrade Path

Next modularization steps when needed:

• Move src/app, src/core, src/models, src/services, and src/widgets into shared packages.
• Replace shell state with Riverpod once multiple apps/features share the same state patterns.
• Add real AnalyticsProvider, MonetizationProvider, and remote config implementations only with privacy/Data safety updates.
• Add golden tests for key screens before scaling the app factory.