mirror of
https://github.com/Dvorinka/1356.git
synced 2026-06-03 19:42:57 +00:00
Initial commit: Project documentation and git setup
This commit is contained in:
Tomas Dvorak
@@ -0,0 +1,215 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user