# ADR 0003: Backendless Local LLM Pipeline

## Status

Accepted

## Context

The product goal is a phone-first relationship memory app. The user shares
messages and text snippets from messaging apps, resolves uncertain identity
matches over time, and receives private extraction plus useful suggestions.

The app is moving away from a server-backed source of truth. Backend sync and
the fake backend should not create or overwrite relationship data unless a
developer explicitly enables REST sync for transport work.

iOS does not provide a reliable always-running background service. Background
work must be treated as opportunistic: run on foreground/app resume, after share
intake, through user-initiated actions, and through scheduled background windows
when the OS grants time.

## Decision

Use a backendless local-first pipeline:

1. Share intake stores raw shared payloads locally.
2. Strong identity matches attach directly to an existing person.
3. Ambiguous, conflicting, or low-information shares stay in `Share Inbox`.
4. Nightly extraction processes only new/resolved share batches.
5. Weekly/on-demand recommendations use compact profile summaries plus prior
   suggestion history to avoid repeats.
6. Internet-grounded recommendations are generated only during the weekly or
   manual recommendation phase, not during nightly extraction.
7. Fake backend sync is inert by default and must not seed local relationship
   records.

## LLM Cost Controls

- Batch new shares into one extraction request per run.
- Use source fingerprints and content hashes to skip repeated extraction.
- Store extraction run fingerprints, completed timestamps, and failures.
- Send compact person tokens and normalized facts instead of names and raw
  history when possible.
- Keep grounded shopping/event prompts separate from nightly extraction because
  web search is more expensive and time-sensitive.
- Include accepted/dismissed/pending suggestion fingerprints in weekly prompts
  so repeated concerts, shops, or gifts are suppressed.

## iOS Background Policy

- Treat scheduled nightly and weekly work as best-effort.
- Always offer manual `Run Now` actions.
- Prefer local notifications after work completes.
- Do not require APNs or a server daemon for core behavior.
- Keep work units short enough to survive iOS background expiration.

## Consequences

- The app remains useful without any backend.
- Share capture and profile building are durable across weeks/months of gradual
  user review.
- Suggestions may run later than the configured wall-clock time on iOS.
- REST sync can still exist as a developer/integration path, but it is not part
  of the primary product loop.