# 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//` 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//` — 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.