Initial commit: Project documentation and git setup

architecture.md

@@ -0,0 +1,92 @@
+# LifeTimer  Technical Architecture
+
+This document describes how the Flutter app and Supabase backend are structured.
+
+## 1. Overall approach
+
+- Mobile first, built with Flutter for Android and iOS.
+- Supabase used for authentication, Postgres database, storage, and real time features.
+- MVVM or Clean Architecture style separation
+  - Presentation, screens and widgets.
+  - View models, state management using Provider or Riverpod.
+  - Data layer, repositories that talk to Supabase clients.
+
+## 2. Flutter project structure
+
+Suggested feature based folder layout
+
+- lib
+  - core
+    - theme, routing, localization, error handling, utilities
+  - data
+    - supabase client setup, repositories, models, mappers
+  - features
+    - auth
+    - onboarding
+    - goals
+    - countdown
+    - social
+    - profile
+    - settings
+    - analytics
+
+Each feature contains its own presentation widgets, view models, and sub repositories where needed.
+
+## 3. Data flow
+
+- UI widgets send user intents to view models.
+- View models call repositories for data access or mutations.
+- Repositories call Supabase client methods
+  - auth api for login, logout, and account management
+  - Postgres queries or rpc calls for business data
+  - storage for media uploads
+  - realtime channels for live updates
+- Results flow back up through view models to update state and rebuild widgets.
+
+## 4. Supabase integration
+
+- Single Supabase client instance configured at app start.
+- Environment configuration uses separate projects or keys for development, staging, and production.
+- Row Level Security used to protect tables so that users only see their own data, unless a profile is explicitly marked public, in which case only a limited subset of non sensitive fields is readable by others.
+- Edge functions may be added later for
+  - computed metrics
+  - scheduled notifications
+  - heavy or sensitive operations.
+
+## 5. Offline and caching
+
+- Local persistence of last known state for
+  - active countdown values
+  - list of goals and their progress
+- Use local database or key value storage package such as Hive or Shared Preferences for small amounts of data.
+- Mark pending writes and retry them when connectivity is back.
+
+## 6. Error handling and logging
+
+- Centralized error handler that maps Supabase and network errors to user friendly messages.
+- Non fatal errors are logged to an analytics or crash reporting service.
+- Critical failures show a fallback screen with safe retry options.
+
+## 7. Testing
+
+- Unit tests for
+  - countdown calculations
+  - rules around starting and locking the countdown
+  - goal progress calculations
+- Widget tests for
+  - goal cards
+  - countdown screen
+  - onboarding flow
+- Basic integration tests for sign up, creating goals, and starting the countdown.
+
+## 8. Security and privacy architecture
+
+- Use Supabase Auth for all authentication; never store passwords or session tokens outside the auth system.
+- Ship only the public anon key in the mobile app; keep the service role key strictly on the server or in Supabase Edge Functions.
+- Enforce Row Level Security on all tables, with policies that
+  - restrict reads and writes to `auth.uid()` for private accounts;
+  - allow limited read only access to selected fields when `users.is_public_profile = true`.
+- Store access tokens only in platform secure storage APIs and never log them.
+- Validate all untrusted input on the server side and avoid constructing dynamic SQL from user data.
+- Minimize personally identifiable information stored in the database and support account deletion.
+- Use structured logging that avoids sensitive fields and route logs to a secure destination.