docs: add project orientation notes
This commit is contained in:
Rijad Zuzo
@@ -0,0 +1,128 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user