# 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.