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.

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

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:

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

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

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

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

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

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

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

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