# Relationship Saver

`relationship_saver` is a local-first Flutter app for managing relationship
context: people, moments, ideas, reminders, share-intake, and lightweight
signals that can later support sync and AI-assisted workflows.

The app currently runs as a prototype-friendly single-client build:

- Flutter + Material UI
- Riverpod for app state
- Hive-backed local persistence by default
- fake backend enabled by default for offline-safe development
- REST/OpenAPI scaffolding for future auth + sync work
- local notifications for reminders
- Android text-share entry and in-app share simulation tools

## Current Architecture

The codebase is mid-migration from an older horizontal structure to a
vertical-slice layout.

- `lib/app/`: app bootstrap, shell navigation, aggregate persistence, shared
  app state
- `lib/features/`: product slices such as `people`, `share_intake`, `sync`,
  `reminders`, `dashboard`, and `settings`
- `lib/core/`: cross-cutting primitives like config, auth, networking, theme,
  and shared presentation helpers
- `lib/integrations/backend/`: backend-facing gateway contracts, REST/fake
  implementations, DTOs, and mappers

Many older root-level files under `lib/features/*` still exist as compatibility
exports. New work should generally target the canonical files in `app/`,
`core/`, or slice subfolders such as `presentation/`, `application/`,
`domain/`, and `data/`.

## Key Runtime Behavior

- Entry point: `lib/main.dart`
- Root widget: `lib/app/relationship_saver_app.dart`
- Authenticated shell: `lib/app/presentation/app_shell.dart`
- Local-first aggregate repository:
  `lib/app/data/relationship_repository.dart`
- Queued sync persistence:
  `lib/features/sync/data/sync_queue_repository.dart`

Notable build-time flags live in `lib/core/config/app_config.dart`:

- `USE_FAKE_BACKEND` defaults to `true`
- `BACKEND_BASE_URL`
- `USE_HIVE_LOCAL_DB`
- `ENABLE_BACKGROUND_SYNC`
- `BACKGROUND_SYNC_INTERVAL_SECONDS`
- `ENABLE_LOCAL_NOTIFICATIONS`
- `ENABLE_WHATSAPP_SHARE_INTAKE`

## Run

Install packages:

```bash
flutter pub get
```

Run with the default fake backend:

```bash
flutter run
```

Run against a REST backend:

```bash
flutter run \
  --dart-define=USE_FAKE_BACKEND=false \
  --dart-define=BACKEND_BASE_URL=https://api.example.com
```

Run tests:

```bash
flutter test
```

Generate code:

```bash
dart run build_runner build --delete-conflicting-outputs
```

## Current Product Areas

- `Dashboard`: overview cards and relationship graph preview/explorer
- `People`: primary workspace for profiles, notes, facts, dates, tags, and
  preference signals
- `Moments`: interaction/capture history
- `Signals`: lightweight prompts derived from local relationship context
- `Ideas`: follow-up and gift/activity/place ideas
- `Reminders`: reminder rules plus local notification scheduling
- `Sync`: queued change diagnostics and repair surface
- `Settings`: environment flags, trust/privacy copy, AI config, share
  simulation, and notification permission actions

## Docs

- [Setup](docs/SETUP.md)
- [Progress Log](docs/progress.md)
- [Open Tasks](docs/open-tasks.md)
- [Client Audit](docs/client-audit-relationship-app.md)
- [Client Implementation Plan](docs/client-implementation-plan.md)
- [Client Iteration Summary](docs/client-iteration-summary.md)
- [Backend ADR](docs/ADR/0002-backend-protocol-rest-openapi.md)
- [OpenAPI Contract](docs/api/openapi.yaml)
- [Contributor Notes](AGENTS.md)

## Known Gaps

- iOS share-sheet integration is still deferred; see `docs/open-tasks.md`
- sync/backend contracts exist, but the product remains primarily local-first
- the repository layer still persists one aggregate snapshot for most local
  state while the slice migration continues