Skip to content

Architecture Overview

Spillway is a native email and work organizer built around user control, recoverability, and explicit boundaries between source evidence, human decisions, AI proposals, and external actions.

Local-first application model

Gmail is the supported mail provider today, but provider data is not the product's organizing model. Spillway maintains local, provider-neutral state for categories, work items, dates, opportunities, learned rules, and user decisions.

Source messages remain evidence. AI classifications and extracted work are proposals that can be reviewed and corrected; later model output must not silently overwrite a human decision.

Durable storage and recovery

SQLite MailStore is the live persistence authority. The application uses incremental writes, bounded/windowed reads, guarded deletion, validated snapshots, backup/restore bridges, and corruption recovery mechanisms.

These systems are intended to make failure visible and recoverable. They do not make pre-alpha software risk-free.

Cross-device synchronization

Spillway distinguishes transport from authority.

The synchronization layer uses durable operation journals, deterministic reducers, materialized state, and account-scoped portable identities. Devices exchange operations; the transport does not decide category or workflow conflicts.

Today:

  • iCloud is the working reference transport between Mac and iPhone;
  • category taxonomy changes synchronize;
  • human category assignments, confirmations, and removals synchronize;
  • AI-only predictions remain device-local;
  • transport failures do not roll back valid local decisions.

The transport boundary remains provider-neutral so future adapters can be added without rewriting domain reducers.

Other domains—including Work Ledger items, requests, dates, opportunities, drafts, and derived Insights state—require their own bounded synchronization slices before they can be described as shared across devices.

Primary Client Readiness

The current architecture is being completed from the platform layer upward:

  1. Platform: MailStore, identity, sync, AI adapters, Calendar and Contacts boundaries.
  2. Client: reading, categorization, Compose, Reply, Forward, HTML rendering, notifications, and cross-device continuity.
  3. Intelligence: historical acquisition, evidence relations, Insights, recommendations, and planning.

Platform boundaries are introduced before downstream features so Planner, scheduling, and relationship intelligence do not hard-code incomplete local assumptions.

Evidence and Insights direction

Future Insights capabilities will derive rebuildable relationships among people, topics, projects, meetings, requests, commitments, and resources from canonical Email, Calendar, Contacts, and Work Ledger evidence.

The relationship graph will be derived state, not canonical truth. Each inference should retain provenance, confidence, recency, temporal validity, staleness behavior, and human correction authority.

Security boundary

The present sync implementation is bounded for personal-use testing. Broader institutional or mixed-trust use requires additional controls such as selective device capabilities, trust-zone isolation, encryption-domain design, revocation, signed operations, and policy inheritance for summaries and other derived data.

See current project status · Explore features · Read the privacy policy