kin/docs/SCOPE.md

# Kin — scope & architecture

*Written 2026-08-09, at project start.*

## What this is

A personal "relational wealth" app: the single place that answers **who
haven't I talked to in too long?** and makes fixing that a two-tap action.
Inspired by Monica CRM, but deliberately thin — one user, one server, no
accounts, no social features.

## Product principles

1. **The due list is the product.** Contacts, notes, and history exist to
   feed one screen: who to reach out to today. Everything else is secondary.
2. **Logging must be cheaper than not logging.** Two taps ("text, today,
   done") or the log stays empty and the due list lies. The old web CRM had
   44 people and 0 interactions — that's the failure mode to design against.
3. **Cadence over guilt.** Each person gets a cadence (weekly → 6-monthly)
   or none at all. No global "you're behind on 30 people" — only people you
   *chose* to track surface in reminders. Snooze is honest: it defers,
   it doesn't fake contact.
4. **Thin client, durable data.** All state lives in the `personal` Postgres
   database on the VPS. The phone caches for instant open and offline
   reading; writes go straight to the API.

## Architecture

```
Pixel (Kin app, Expo RN) ──Bearer token──▶ Caddy ──▶ crm container (Bun+Hono) ──▶ personal-db (Postgres)
Browser (web UI)         ──basic_auth───▶  ↑ same API, same data
```

- **Server**: the existing `crm` container, extended. Hono + porsager/postgres
  on Bun. Now has boot-time SQL migrations (`schema_migrations`), a
  `GET /api/due` endpoint, cadence/snooze/archive columns, relationship
  create/delete, and Bearer-token auth for non-browser clients.
- **Due math** (server): `urgency = days_since_last_contact / cadence_days`,
  anchored on `created_at` for never-contacted people so new adds surface
  immediately. `overdue` ≥ 1.0, `due_soon` ≥ 0.75. Sorted by urgency, so a
  weekly friend 3 days late outranks a yearly contact 3 days late.
- **App**: Expo SDK 57 + expo-router, structured like the GTD app (read-cache
  store on `useSyncExternalStore` + AsyncStorage, refresh on
  foreground/focus). Dark warm theme, Pixel 9 XL first.
- **Reminders**: local notifications only, no server push. On every sync the
  app reschedules a daily digest for the next 7 days ("N people are due for a
  catch-up") at the configured hour. If the app isn't opened for a week, the
  notifications run out — which is itself the right nudge. Server-side
  push via the existing ntfy container is the v2 escape hatch if this proves
  too passive.

## Screens

| Screen | Job |
|---|---|
| **Today** (home) | Due list in sections: Reach out / Coming up / On track / Snoozed. Quick-log button on every row. Empty state doubles as onboarding. |
| **People** | Whole network, client-side search + tag filter (44 people — no server round-trips). |
| **Person** | Contact actions (Message/Call/WhatsApp/Email deep links), cadence picker, log + snooze, notes, relationships, history (long-press to delete). |
| **Log** (modal) | Type chips + today/yesterday + optional note. Two taps minimum. |
| **Add/Edit** (modal) | Name, phone, email, location, tags, notes, cadence. |
| **Settings** (modal) | Server URL, token, reminder hour. Probes the API before saving. |

## Deliberately out of v1

- **Offline write queue** — GTD's op-queue store is proven but heavy; a
  relationships app tolerates "log it when you're back online". Revisit if it
  annoys in practice.
- **Birthday reminders** — column exists (`people.birthday`), UI doesn't.
- **Relationship editing in-app** — API supports create/delete now; app only
  displays. Add when graph curation actually matters.
- **Web UI parity** — the vanilla-JS web UI still works for bulk edits at
  crm.rehbock.xyz; it doesn't know about cadence yet.
- **Contact import from the phone** — seed data came from the newsletter
  subscriber list; `expo-contacts` import is a v2 candidate.
- **Multi-user / open-source hardening** — single-user by design. The repo is
  structured to be open-sourceable (no secrets in git, migrations from
  scratch, auth documented), but no login system until someone else needs it.

## Infrastructure facts

- VPS dir: `~/personal/crm` (container `crm`, network `caddy_net` +
  `personal-db_default`). DB: `personal` in the shared `personal-db` Postgres.
- Caddy: `crm.rehbock.xyz`; Bearer requests bypass basic_auth (app validates),
  everything else challenges.
- CI: Gitea Actions on the desktop runner (label `desktop`), signed APK per
  push to main, released as `kin-v1.<run>.apk` for Obtainium.
- Keystore: `~/.android-keys/kin-release.jks`, alias `kin` — distinct from
  GTD's so Android treats the apps independently.