# AGENTS.md

This file is the fastest orientation doc for future coding agents working in
this repository.

## Project Summary

`relationship_saver` is a Flutter app for capturing and maintaining
relationship context locally. The app already supports:

- people profiles with aliases, notes, tags, facts, important dates, and
  preference signals
- moments, ideas, reminders, and dashboard tasks
- Android/in-app share-intake flows with inbox-first review for ambiguous
  content
- local notification scheduling for reminders
- fake-backend auth/sync flows and REST/OpenAPI scaffolding for later backend
  work

The current product posture is local-first and prototype-oriented, not a fully
server-backed production app.

## Canonical Code Paths

Start here before changing behavior:

- `lib/main.dart`: app entry
- `lib/app/relationship_saver_app.dart`: root widget, auth gate, global
  listeners
- `lib/app/presentation/app_shell.dart`: responsive shell and navigation
- `lib/app/data/relationship_repository.dart`: aggregate local-first write
  boundary
- `lib/features/sync/data/sync_queue_repository.dart`: queued mutation store
- `lib/integrations/backend/backend_gateway_provider.dart`: fake vs REST
  gateway selection
- `lib/core/config/app_config.dart`: runtime flags

## Architecture Reality

The repo is in a vertical-slice migration.

- Canonical structure is `lib/app`, `lib/features`, `lib/core`,
  `lib/integrations`
- Many older files at slice roots are compatibility exports
- Prefer editing canonical files under:
  - `presentation/`
  - `application/`
  - `domain/`
  - `data/`
- Avoid expanding legacy compatibility files unless the task is specifically
  about keeping old imports working

Useful orientation docs:

- `lib/README.md`
- `lib/app/README.md`
- `lib/features/README.md`
- `lib/core/README.md`
- slice READMEs inside `lib/features/*`

## Main Product Slices

- `people`: primary relationship workspace and richest data model
- `share_intake`: normalized shared payloads, review flows, inbox routing
- `sync`: queued changes, push/pull orchestration, rejection repair
- `reminders`: local reminder rules and notification scheduling
- `dashboard`: overview metrics and graph preview/explorer
- `settings`: trust/privacy copy, AI config, share simulation, environment
  diagnostics
- `auth`: sign-in UI and session lifecycle

## Storage And Data Flow

- Local state is centered on `LocalDataState` in `lib/app/state/`
- `LocalRepository` persists a mostly single aggregate snapshot
- Default local store is Hive; shared preferences remains as legacy fallback
  and migration path
- Sync queue state is persisted separately through the sync store abstraction
- The app is intentionally offline-safe in fake-backend mode

## Runtime Flags

Defined in `lib/core/config/app_config.dart`:

- `USE_FAKE_BACKEND=true` by default
- `BACKEND_BASE_URL`
- `USE_HIVE_LOCAL_DB=true` by default
- `ENABLE_BACKGROUND_SYNC=true` by default
- `BACKGROUND_SYNC_INTERVAL_SECONDS=180` by default
- `ENABLE_LOCAL_NOTIFICATIONS=true` by default
- `ENABLE_WHATSAPP_SHARE_INTAKE=true` by default

If behavior seems surprising, check the active `--dart-define` values first.

## Backend Boundary

- Transport contract is documented in `docs/api/openapi.yaml`
- Architectural rationale lives in
  `docs/ADR/0002-backend-protocol-rest-openapi.md`
- `BackendGatewayFake` is still the default development path
- `BackendGatewayRest` is the real transport boundary when fake mode is off

## Known Limitations

- iOS share extension work is deferred; see `docs/open-tasks.md`
- Native share-entry support is stronger on Android than iOS
- Sync scaffolding exists, but not all newer local entities are mapped to the
  backend protocol yet
- The repo currently contains a lot of in-flight migration work and
  compatibility exports

## Working Guidance

- Read the relevant slice README before changing a feature
- Treat existing uncommitted changes as user work unless you created them
- Prefer canonical slice files over compatibility exports
- Keep docs aligned with the verified code, not with older plans
- When changing architecture-level behavior, update the nearest README or this
  file if it affects future orientation

## Useful Commands

```bash
flutter pub get
flutter test
flutter analyze
dart run build_runner build --delete-conflicting-outputs
```