Offline-First Architecture: How Styrby Handles Lost Connections

Phones lose connectivity regularly: elevators, subways, buildings with poor signal, airplane mode. A mobile developer tool that shows a blank screen when offline is not useful to someone checking on an agent session during a commute. Styrby is designed to be useful when connectivity drops, not just when everything is online.

Why Offline-First for a Developer Tool

Offline-first means the app always has data to display. Cached sessions, cost summaries, and agent configurations are available immediately. When connectivity returns, changes sync automatically. The user experience should be identical whether you are on a fast connection or a spotty one.

Storage Layers

Mobile: SQLite via Expo

The iOS app uses Expo SQLite for persistent local storage. SQLite is a single-file relational database that is fast, reliable, and widely deployed. Key tables mirrored locally:

• sessions: Metadata for recent sessions (agent, status, cost, timestamps)
• session_messages: Encrypted message content for bookmarked and recent sessions
• cost_records: Daily cost summaries for the dashboard
• offline_command_queue: Commands queued while offline

The local database stores the last 30 days of session metadata and the last 7 days of message content. Older data is fetched on demand when online.

Web Dashboard: IndexedDB

The web dashboard uses IndexedDB for offline caching. The schema mirrors the mobile SQLite structure. IndexedDB is asynchronous and has larger storage limits than localStorage, making it suitable for caching session data.

The Offline Command Queue

When you are offline, certain actions queue instead of failing:

• Approving or denying a pending permission request
• Bookmarking a session
• Adjusting budget alert thresholds
• Updating notification preferences

These actions are stored in the offline_command_queue table with a timestamp and operation type. When connectivity returns, the queue drains in order.

// Simplified queue structure
{
  id: "cmd_abc123",
  operation: "permission_approve",
  payload: { sessionId: "ses_xyz", requestId: "req_456" },
  createdAt: "2026-03-15T14:30:00Z",
  status: "pending"  // pending → syncing → synced | failed
}

Sync Protocol

When the device comes back online, synchronization happens in three phases:

1. Drain the command queue. Pending commands are sent to the server in chronological order. If a command fails (e.g., the permission request has already timed out), it is marked as failed with the reason, and the next command proceeds.
2. Pull fresh data. The app requests updates since the last sync timestamp. The server responds with new sessions, updated cost records, and any configuration changes made from other devices.
3. Resolve conflicts. If the same record was modified on multiple devices while both were offline, server wins. Local changes that conflict are discarded with a notification to the user.

After the initial catch-up, Supabase Realtime handles ongoing updates through WebSocket subscriptions. New session data, cost updates, and permission requests push to the device as they happen.

Conflict Resolution: Server Wins

Styrby uses a simple conflict resolution strategy: the server is always right. This works because most Styrby data flows in one direction (CLI to server to mobile). The rare conflict scenario is when two devices modify the same configuration while both are offline. In practice, this almost never happens because configuration changes are infrequent and typically happen from a single device.

More sophisticated conflict resolution (CRDTs, operational transforms) would add complexity without solving a real problem. Server-wins is the right tradeoff for this use case.

What Does Not Work Offline

Offline mode has clear limitations:

• Live session monitoring. You cannot watch a running agent session without connectivity. The session continues on your workstation; you just cannot see it until you reconnect.
• Cost tracking. Cost data updates when new data syncs. Offline, you see the last-known costs.
• Permission approvals are delayed. Queued approvals are sent when you reconnect. If the agent is waiting for approval, it blocks until the queue drains. For time-sensitive permissions, offline mode means the agent waits.

Testing Offline Behavior

The Styrby mobile app has a developer mode that simulates offline conditions. Toggle airplane mode in the app settings to test how the UI behaves without connectivity, verify that the command queue fills correctly, and confirm that sync works when you toggle back online.