docs: add project orientation notes

README.md

@@ -1,17 +1,120 @@
-# relationship_saver
+# Relationship Saver
 
-A new Flutter project.
+`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.
 
-## Getting Started
+The app currently runs as a prototype-friendly single-client build:
 
-This project is a starting point for a Flutter application.
+- 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
 
-A few resources to get you started if this is your first Flutter project:
+## Current Architecture
 
-- [Learn Flutter](https://docs.flutter.dev/get-started/learn-flutter)
-- [Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
-- [Flutter learning resources](https://docs.flutter.dev/reference/learning-resources)
+The codebase is mid-migration from an older horizontal structure to a
+vertical-slice layout.
 
-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+- `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