1356/flutter-project-structure.md

LifeTimer — Flutter Project Structure

This document describes the recommended folder and file structure for the LifeTimer Flutter app, aligned with the architecture and flows.

Assumption: you will start from a standard flutter create lifetimer project, then adapt the lib/ directory as follows.

---

1. High level layout

• lib/
  • main.dart — app entrypoint, initializes Supabase and runs LifeTimerApp.
  • bootstrap/ — initialization helpers (Supabase client, dependency injection, env config).
  • core/ — cross cutting concerns (theme, routing, localization, widgets, utils, error handling).
  • data/ — shared data layer code (models, repositories, Supabase clients).
  • features/ — feature modules (auth, onboarding, goals, countdown, social, profile, settings, analytics).

---

2. lib/main.dart

Responsibilities:

• Ensure Flutter bindings are initialized.
• Initialize Supabase client (using config from bootstrap/).
• Run the LifeTimerApp widget.

File:

• lib/main.dart

---

3. Bootstrap and configuration

Folder:

• lib/bootstrap/
  • bootstrap.dart — high level bootstrap() function called from main.dart (sets up Supabase, error handlers, env).
  • supabase_client.dart — creates and exposes a configured Supabase client instance.
  • env.dart — holds environment configuration (Supabase URL, anon key, build flavor hooks).

---

4. Core module

Folder:

• lib/core/
  • theme/
    • app_theme.dart — light/dark theme definitions, colors, typography.
  • routing/
    • app_router.dart — central route definitions and navigation helpers.
  • localization/
    • l10n.dart — localization setup (generated or custom wrapper).
  • widgets/
    • primary_button.dart — reusable CTA button.
    • app_scaffold.dart — base scaffold with consistent background and app bar style.
    • bottom_nav_scaffold.dart — scaffold wiring bottom navigation.
    • loading_indicator.dart — standard loading widget.
    • empty_state.dart — reusable empty state widget.
  • errors/
    • failure.dart — domain error types.
    • error_mapper.dart — maps Supabase / network errors to user friendly messages.
  • utils/
    • date_time_utils.dart — countdown calculations, formatting.
    • validators.dart — input validation helpers.
  • state/ (if using Riverpod/Provider wrappers)
    • providers.dart — top level providers (Supabase client, theme mode, auth state).

---

5. Data layer

Folder:

• lib/data/
  • supabase/
    • supabase_client_provider.dart — exposes Supabase client to the app (e.g., via Riverpod/Provider).
  • models/
    • user_model.dart — app level User model.
    • goal_model.dart — Goal model.
    • goal_step_model.dart — GoalStep model.
    • activity_model.dart — Activity model.
  • repositories/
    • auth_repository.dart — login, logout, token refresh.
    • user_repository.dart — profile read/update, visibility toggle.
    • goals_repository.dart — CRUD for goals and steps, enforce 1–20 limit.
    • countdown_repository.dart — start countdown, compute remaining time.
    • social_repository.dart — followers, feeds, leaderboards (Phase 2+).
    • notifications_repository.dart — notification preferences and tokens.

Repositories hide Supabase queries behind a clean API, so features do not talk to Supabase directly.

---

6. Feature modules

Each feature lives under lib/features/<feature_name>/ with a simple structure:

• presentation/ — screens and widgets.
• application/ — state management (view models, controllers, providers).
• domain/ (optional) — feature specific entities and logic.

6.1 Auth feature

• lib/features/auth/presentation/
  • auth_gate.dart — decides whether to show auth screens or main app based on session.
  • sign_in_screen.dart
  • sign_up_screen.dart
  • auth_loading_screen.dart — transient during OAuth redirects.
• lib/features/auth/application/
  • auth_controller.dart — wraps auth_repository, exposes current user/session state.

6.2 Onboarding feature

• lib/features/onboarding/presentation/
  • onboarding_intro_screen.dart
  • onboarding_how_it_works_screen.dart
  • onboarding_motivation_screen.dart
• lib/features/onboarding/application/
  • onboarding_controller.dart — tracks whether onboarding is completed.

6.3 Goals feature

• lib/features/goals/presentation/
  • goals_list_screen.dart — list of goals, empty state, add/edit buttons.
  • goal_edit_screen.dart — create/edit goal (title, description, location, image, milestones).
  • goal_detail_screen.dart — view and update progress, mark as completed.
• lib/features/goals/application/
  • goals_controller.dart — loads goals, enforces max 20, exposes list/state.
  • goal_detail_controller.dart — state for a single goal.

6.4 Countdown feature

• lib/features/countdown/presentation/
  • home_countdown_screen.dart — main world-time inspired countdown UI.
  • countdown_summary_screen.dart — shown after countdown ends, summary stats.
• lib/features/countdown/application/
  • countdown_controller.dart — calculates remaining time, exposes streams/timers.

6.5 Social feature (Phase 2+)

• lib/features/social/presentation/
  • social_feed_screen.dart
  • leaderboards_screen.dart
  • public_profile_screen.dart
• lib/features/social/application/
  • social_feed_controller.dart
  • leaderboards_controller.dart

6.6 Profile feature

• lib/features/profile/presentation/
  • profile_screen.dart — shows own profile, countdown info, stats.
• lib/features/profile/application/
  • profile_controller.dart — loads and updates profile, visibility, avatar.

6.7 Settings feature

• lib/features/settings/presentation/
  • settings_home_screen.dart
  • account_settings_screen.dart
  • appearance_settings_screen.dart
  • notification_settings_screen.dart
  • privacy_settings_screen.dart — global Public/Private toggle, blocking.
  • about_challenge_screen.dart
• lib/features/settings/application/
  • settings_controller.dart — wraps repositories for user preferences.

6.8 Analytics / insights (Phase 3)

• lib/features/analytics/presentation/
  • insights_screen.dart — charts and stats.
• lib/features/analytics/application/
  • insights_controller.dart

---

7. Navigation and route names

• Central router file: lib/core/routing/app_router.dart.
• Define named routes for key screens, grouped by feature, e.g.:
  • / → AuthGate (decides between auth vs main app).
  • /onboarding/* for onboarding screens.
  • /home → HomeCountdownScreen.
  • /goals, /goals/:id, /goals/:id/edit.
  • /social, /social/leaderboards, /u/:username.
  • /settings/* for settings sections.

The router uses the navigation library you choose (Navigator 2.0, go_router, etc.); this file is the single source of truth for destinations.

---

8. State management

If you use Riverpod or Provider:

• Global providers in lib/core/state/providers.dart:
  • supabaseClientProvider
  • authControllerProvider
  • themeModeProvider
• Feature specific providers next to controllers in their application/ folders.

---

9. Testing structure

Mirror the feature structure under test/:

• test/core/ — utilities, date/time tests, error mapping tests.
• test/data/ — repository tests with mocked Supabase client.
• test/features/<feature_name>/ — unit and widget tests for each feature.

This structure keeps the app modular and makes it easy to grow features (e.g., adding more social or analytics functionality) without losing clarity.