L@tr architecture #

Components #

• Web (apps/web) — Next.js App Router, ATProto OAuth in the browser, thin client to the L@tr gateway for save/list/state workflows.
• Gateway (services/latr-gateway) — Swift/Hummingbird HTTP service: OAuth/DPoP gate, PDS write-through, server-side Open Graph fetch, Standard.site AT URI discovery.
• Stygian-Tech/latr-kit (GitHub) — Swift LatrKit library (SavedLibrary, RepositoryClient, URLNormalizer, …). SwiftPM git dependency from services/latr-gateway.
• Stygian-Tech/latr-packages (GitHub) — TS contracts (gateway-client, record-keys, lexicons). Root git dependency; not duplicated under packages/.
• packages/latr-web-client — Monorepo-only shared save/gateway client for web + extension (no separate org repo).

flowchart LR
  Browser[L@tr_web]
  Gateway[L@tr_gateway]
  PDS[User_PDS]
  AppView[Bluesky_AppView]
  Browser -->|"OAuth_DPoP"| Gateway
  Gateway -->|"com.atproto.repo.*"| PDS
  Browser -->|"public_reads"| AppView
  Browser -->|"read_only_getRecord"| PDS

Data ownership #

Data	Location
Saved items	link.latr.saved.item on the user’s repo
External URL wrappers	link.latr.saved.external on the user’s repo
Session tokens	OAuth client browser storage (IndexedDB / memory)
Optional UI cache	Browser localStorage / memory (React Query persistence)

Save, list, archive, and unsave run through the L@tr gateway. The web app no longer performs direct L@tr com.atproto.repo.* writes.

Flows (summary) #

1. Save external URL — Web POSTs to gateway → normalize URL → upsert link.latr.saved.external → upsert link.latr.saved.item → server OG enrichment.
2. Save ATProto record — Web POSTs subject URI (+ optional linked web URL) → gateway upserts link.latr.saved.item with preview metadata when OG is available.
3. List — Gateway lists link.latr.saved.item; web resolves each subjectUri for display (App View + read-only repo get).
4. Unsave / archive — Gateway PATCH/DELETE on saved-item records.

OAuth scopes #

Repository writes require explicit repo: scopes for both collections, aligned with apps/web/public/client-metadata.json. Users must re-auth after scope changes.

See latr-gateway.md for route contracts, deployment, and auth constraints.