05 · Architecture

Five layers: the websites in isolated web views, one typed bridge, a native core that owns identity, schedule, alerts and capture, a vault client that owns all private data, and system surfaces (widgets, Live Activities, Siri) fed from a shared App Group store.

The layers

┌───────────────────────────── iPhone / iPad ─────────────────────────────┐
│  System surfaces   Widgets · Live Activity · Siri/Shortcuts · Spotlight │
│                    Notifications · Share extension · Control Center     │
│                         ▲ reads the App Group store only                │
│  Native core       Identity · Schedule · Alerts · Capture · Reader      │
│                         ▲                         ▲                     │
│  Bridge            pt.* messages (WKScriptMessageHandlerWithReply)      │
│                         ▲                         │                     │
│  Web views         promptugal.news · web-summit.sgit.ai · newsroom …    │
│                    one WKWebsiteDataStore per site, App-Bound Domains   │
│                                                   ▼                     │
│  Vault client      Swift: read, cache, sync, commit, push               │
│                    keys: Keychain + Secure Enclave, unlocked by passkey │
└──────────────────────────────────┬──────────────────────────────────────┘
                                   ▼
          dev.send.sgraph.ai (ciphertext only)   ·   promptugal.news /api/v1 (public)

The bridge

One message handler, pt, registered in its own WKContentWorld and only on App-Bound Domains. The page calls await window.webkit.messageHandlers.pt.postMessage({op, …}) and gets a reply. The website detects the app with one injected flag (window.ptApp = {version, ops}) and falls back to its browser behaviour when the flag is missing, so the same page works in Safari and in the app.

op	Direction	What it does	Who can call it
`schedule.get` / `schedule.set`	page → app	Read or replace picks, in the `nr.schedule.v1` shape	promptugal.news, web-summit.sgit.ai
`schedule.changed`	app → page	Fires the page’s existing `nr:schedule` event	the same
`notify.plan`	page → app	Ask for reminders for given picks. The app asks permission once	the same
`vault.status` / `vault.load` / `vault.save` / `vault.list`	page → app	The native implementation of the page’s `window.__vault`. Keys stay native	promptugal.news (later, vault apps)
`key.sign`	page → app	Sign bytes with my team key after Face ID. Returns the signature, never the key	web-summit.sgit.ai
`identity.get`	page → app	Who am I (team id, display name). No secrets	team sites
`capture.open`	page → app	Open the native scanner, recorder or camera, and return the saved item’s id	all
`share`	page → app	Native share sheet for a page or entity	all

Rules. Every op checks the calling frame’s origin against an allow-list. Every op that touches a secret needs a fresh Face ID (LAContext, reuse window of 60 seconds or less). No op returns key material. The list is versioned, and both sides ignore unknown ops.

Stores

Store	Holds	Where	Synced by
Feed cache	agenda, events, news, wires	Application Support (today’s `content.json`)	the native reader’s refresh
Shared App Group store	next items, badge counts, the last sync time	App Group container (SQLite or JSON)	written by the core, read by widgets and intents
Vault object cache	encrypted `obj-cas-imm-*` objects	Caches, kept forever (objects never change)	the vault client
Vault working state	decrypted picks, stars, notes, contacts	memory, plus a protected file (`NSFileProtectionComplete`)	the vault client, on unlock
Keys	wrapped master key, team keys, device signing key	Keychain (`.biometryCurrentSet`, this device only), Secure Enclave	never synced. Recovery through the passkey
Web storage	each site’s own `localStorage`, IndexedDB and service worker	one `WKWebsiteDataStore` per site	not a source of truth. Rebuilt from the vault through the bridge

Sync

Pull. Fetch the ref. If the commit is new, walk only the trees and objects not already cached (-imm- objects never change). Do this on open, on pull-to-refresh, and in BGAppRefreshTask (about 30 seconds, at times iOS chooses, never after a force quit).
Push. The local change becomes a commit on this device’s branch, signed in the Secure Enclave, then pushed. A failed push stays queued and retries on the next open or background run.
Merge. Picks merge by id (the union, with the latest at deciding a removal), the same rule the website uses. Other paths follow sgit’s merge. A conflict is shown, never silently resolved.
Feeds. The public feeds are separate and need no unlock.

Security model

Threat	Defence
A page script tries to read keys	Keys never enter a web view. The bridge returns results, not keys. The bridge lives in its own content world and checks the frame origin.
One site reads another site’s data	A separate `WKWebsiteDataStore` per site. Origin checks on every bridge call.
A stolen, unlocked phone	Secrets need a fresh Face ID. The master key is wrapped by a Secure Enclave key that stops working when Face ID enrolment changes.
A lost phone	Nothing usable is on it without Face ID. The passkey and recovery code restore access on a new device.
The server is compromised	It has only ciphertext and opaque IDs. The client verifies object hashes (`obj-cas-imm-` = SHA-256 of the ciphertext) and commit signatures.
A bad website release	The app pins the bridge to known ops. The website cannot ask for anything new without an app update.
WebKit clears website storage	Web storage is a cache. The vault is the source of truth.

Targets

iOS 18 minimum is recommended. It brings passkey PRF, broadcast Live Activities, Control Center controls and Spotlight IndexedEntity. Apple Intelligence features (Foundation Models, iOS 26, iPhone 15 Pro and later) stay optional.
Extensions: a widget, a Live Activity, an App Intents extension and a share extension. All of them read the App Group store only, never the vault directly.
No third-party packages, as today. Everything above is in Apple’s SDK.