Offline-First Architecture

project: hinata-infrastructuretype: architecturecaptured: 2026-05-06source: telegram Implementation strategy for persistence without laptop availability. The system must work when the laptop is off.

TierMechanismWhen It Runs

CaptureiOS Shortcuts → iCloud syncAlways (phone always on) Processscripts/session-start.sh + .plist daemonsOn laptop wake or scheduled SynthesiseClaude sessions (Hinata, Commanders)When you invoke

What Works When Laptop Is Off

1. Inbox capture (Telegram → Shortcuts → iCloud)

• iOS Shortcuts reads Telegram → writes to Sandpit/hinata/inbox/{date}-{summary}.md

• iCloud syncs to laptop automatically

• When laptop wakes, session-start.sh detects new inbox files and routes to Canary

2. Daily daemon auto-runs (via .plist)

• scripts/morning-routine.plist → fires at 07:00 (Snorlax wind-down log prompt)

• scripts/evening-sync.plist → fires at 21:00 (session-end check, memory flush)

• These run even if Claude hasn't been invoked — they just write to files. Hinata reads them on next session start.

3. Async decision logging

* When offline, jot decisions to `Sandpit/hinata/logs/async-decisions-{date}.md`

* On next session, Jimmy Neutron reads these and routes to appropriate Commanders

* No backlog congestion — each decision gets processed once

Critical Implementation (Do First)

A. Telegram → iOS Shortcuts auto-capture

  * Shortcut name: `Hinata Inbox Capture`

  * Trigger: NFC tap or Telegram notification

  * Action: Read last Telegram message → append to `Sandpit/hinata/inbox/{YYYY-MM-DD}-{first-3-words}.md`

  * iCloud sync: Automatic (Files app on iOS syncs Sandpit folder)

B. macOS .plist daemons

~/Library/LaunchAgents/
  - hinata-morning.plist (07:00 daily)
  - hinata-evening.plist (21:00 daily)

Both write to /Sandpit/hinata/logs/ — no Claude needed. On session start, Hinata reads these.

C. Offline decision buffer

    * Write decisions to `Sandpit/hinata/logs/async-{date}.md` when offline

    * Session start: Jimmy reads async files → routes to Commanders

    * Clear after routing

Risk

Inbox overload if you capture but don't route. Mitigate: Async files auto-archive after 7 days to Sandpit/hinata/logs/archive/. Canary reports inbox size weekly.

◆ hinata · projects/hinata-infrastructure/architecture/offline-first.html · phase-19 conversion