Add maintainer onboarding documentation

2026-07-03 12:44:15 +02:00
parent 5d80af375e
commit d80486b25e
15 changed files with 1273 additions and 28 deletions
@@ -0,0 +1,92 @@
+# Onboarding
+
+This app is a local-first Flutter prototype for capturing relationship context:
+people, moments, reminders, ideas, shared messages, preference signals, and
+private AI-assisted suggestions.
+
+The most important product constraint is trust. The app should preserve
+relationship details locally by default, avoid accidental profile matching, and
+send only pseudonymous, reviewed context to LLM flows.
+
+## First Hour
+
+1. Read this file, then [Architecture](ARCHITECTURE.md), [Data Model](DATA_MODEL.md),
+   and [Feature Map](FEATURE_MAP.md).
+2. Run `flutter pub get`.
+3. Run `flutter analyze`.
+4. Run focused tests before full tests:
+   - `flutter test test/features/share_intake`
+   - `flutter test test/features/ai_digest`
+   - `flutter test test/features/local`
+5. Run the app with the fake backend:
+
+```bash
+flutter run --dart-define=USE_FAKE_BACKEND=true
+```
+
+## Project Posture
+
+The app is not a fully server-backed production product yet. It is a
+prototype-friendly, local-first app with REST/OpenAPI scaffolding for later
+backend work. Fake backend mode is the default development path and should remain
+safe offline.
+
+Current product strengths:
+
+- people profiles with aliases, notes, tags, facts, dates, and preference
+  signals
+- manual capture for moments, ideas, reminders, and dashboard tasks
+- share intake with inbox-first review for ambiguous content
+- local notifications for reminders
+- private weekly AI digest with pseudonymous prompt payloads
+- fake backend auth/sync plus REST gateway boundary
+
+Current constraints:
+
+- data is mostly stored as one local aggregate snapshot
+- many backend mappings are incomplete for newer local entities
+- iOS share support has native targets, but real device behavior still needs
+  continued verification
+- tests are good for parsers/repositories/widgets, but native share and
+  background scheduling need manual device testing
+
+## Daily Development Commands
+
+```bash
+flutter pub get
+flutter analyze
+flutter test
+dart run build_runner build --delete-conflicting-outputs
+```
+
+Useful run modes:
+
+```bash
+flutter run --dart-define=USE_FAKE_BACKEND=true
+flutter run --dart-define=USE_FAKE_BACKEND=false --dart-define=BACKEND_BASE_URL=https://your-api
+flutter run --dart-define=ENABLE_BACKGROUND_SYNC=false
+flutter run --dart-define=ENABLE_LOCAL_NOTIFICATIONS=true
+```
+
+## Where To Start For Common Work
+
+| Task | Start Here |
+| --- | --- |
+| Add or change persisted relationship data | `lib/app/state/local_data_state.dart`, model file in `lib/features/*/domain/`, repository part in `lib/app/data/` |
+| Change profile UI | `lib/features/people/presentation/` |
+| Change share capture | `lib/features/share_intake/`, `lib/app/data/relationship_repository_share.dart`, native files under `ios/` or Android manifest |
+| Change AI suggestions | `lib/features/ai_digest/`, `lib/core/llm/` |
+| Change reminder behavior | `lib/features/reminders/`, `lib/app/data/relationship_repository.dart` schedule reconciliation |
+| Change backend sync | `lib/features/sync/`, `lib/integrations/backend/`, `docs/api/openapi.yaml` |
+| Add settings/debug tools | `lib/features/settings/presentation/settings_view.dart` |
+
+## Non-Negotiable Maintainer Rules
+
+- Prefer canonical slice files under `presentation/`, `application/`, `domain/`,
+  and `data/`.
+- Do not expand compatibility exports unless preserving old imports is the task.
+- Keep local-first behavior working in fake backend mode.
+- Treat ambiguous shared identities as inbox items, not auto-linked profiles.
+- Never include names, aliases, sender names, source URLs, or raw shared text in
+  scheduled digest prompts.
+- Update the nearest doc when changing architecture-level behavior.