Rijad Zuzo
129 lines
4.3 KiB
Markdown
129 lines
4.3 KiB
Markdown
# 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
|
|
```
|