GAL-1010 - Why Collaborative Cloud Sync is Deferred in Alpha

Living Document Notice
Published 2026-09-19. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

Why Collaborative Cloud Sync is Deferred in Alpha

Summary

Explaining the deliberate omission of multi-user sync and real-time collaboration. Hardening single-device storage guarantees before opening networked boundaries.

Sync is easy to demo poorly and exceptionally difficult to build reliably. In early software development, premature introduction of cloud synchronization often forces compromises: complex backend server dependencies, leaky database abstractions, and high maintenance overhead that distracts from core application quality.

We made the intentional decision to defer cloud sync and collaborative multi-user editing in the alpha release of Galley. Our priority is making single-device local storage dependable first.

The Cost of Premature Synchronization

Introducing real-time cloud sync early creates significant engineering liabilities:

1. Schema Calcification: Once database rows are synchronized across disparate client versions, modifying table schemas requires database migrations that slow rapid product iteration.
2. Conflict Complexity: Merging conflicting edits across devices without data loss requires CRDTs or operational transforms. Implementing these before data models are mature leads to bugs.
3. Loss of Local-First Simplicity: Applications designed cloud-first frequently assume continuous network availability, breaking basic offline workflows when a kitchen device loses Wi-Fi connection.

By deferring network synchronization, we retain the freedom to refine the underlying recipe schema, improve ingredient tokenization, and test storage formats without breaking remote replica nodes.

The Phased Foundation Strategy

Galley follows a phased engineering progression, ensuring that each persistence layer is hardened before building the next:

Phase 1: Local Hardening (Current Alpha)
└── SQLite transactional storage + filesystem Markdown exports
    └── Complete offline durability, zero data loss verification

Phase 2: Archive Interchange (Near-Term Beta)
└── Encrypted snapshot exports and peer-to-peer import/export
    └── Manual backup bundles, cross-device file sharing

Phase 3: Sovereign Synchronization (Stable Release)
└── Local-first sync protocols (e.g. CRDT-backed event journals)
    └── Direct peer-to-peer synchronization without mandatory central servers

Append-Only Operation Journals

Even without live cloud synchronization, Galley prepares for future distributed replication by recording state changes as append-only operation events inside SQLite:

CREATE TABLE operation_journal (
    op_id INTEGER PRIMARY KEY AUTOINCREMENT,
    entity_id TEXT NOT NULL,
    entity_type TEXT NOT NULL,
    operation TEXT CHECK(operation IN ('insert', 'update', 'delete')),
    payload_diff TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Because every recipe edit produces a discrete journal entry, future sync layers can replay operations across devices without requiring whole-database overwrites or complex diffing algorithms.

Architectural Milestone Comparison

The table below outlines our storage capabilities across release milestones:

Capability	Alpha Phase (Current)	Beta Phase	General Availability
Storage Engine	Local SQLite (WAL)	Local SQLite + Snapshot Bundles	Local SQLite + CRDT Journal
Network Requirements	100% Offline	100% Offline (Manual file transfer)	Optional Peer-to-Peer Sync
Data Export	Plain JSON / CommonMark	Encrypted Galley Vault Archive	Live Multi-Device Replicas
Backup Responsibility	Standard filesystem backup	One-click vault snapshot	Automated local backups

Schema Evolution Without Remote Migrations

By maintaining an isolated local boundary during Alpha, schema migrations remain simple. If a table definition requires adjustment, the database file can be re-indexed directly from the local Markdown projections in milliseconds.

Once networked synchronization is introduced, changing a column type or adding a required constraint becomes significantly more difficult, requiring multi-version compatibility shims and phased migrations across client nodes. Deferring sync allows us to perfect the data model first.

By focusing entirely on single-device reliability during Alpha, we ensure that the core recipe ingestion and kitchen display experiences are stable and dependable before introducing networked complexity.

---

• Directus Target: galley
• Garden Source Reference: CRDT Sync Roadmap, Alpha Constraints, Distributed State, MOC - Culinary & Domain Workspaces, MOC - The Kitchen Chaos Factor, MOC - Bosun PKM Tools