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
• SENTRY_DSN defaults to the Bugsink project DSN
• SENTRY_ENVIRONMENT
• SENTRY_RELEASE

Run

Install packages:

flutter pub get

Run with the default fake backend:

flutter run

Run against a REST backend:

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

Build a release with explicit Bugsink/Sentry metadata:

flutter build apk --release \
  --dart-define=SENTRY_ENVIRONMENT=production \
  --dart-define=SENTRY_RELEASE=relationship_saver@1.0.0+1

Run tests:

flutter test

Generate code:

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

• Documentation Index
• Onboarding
• Architecture
• Data Model
• Feature Map
• Implementation Playbook
• Setup
• Progress Log
• Open Tasks
• Client Audit
• Client Implementation Plan
• Client Iteration Summary
• Backend ADR
• OpenAPI Contract
• Contributor Notes

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