Architecture
Epheme Architecture — Vision, Components, and Evolving Plan
Epheme is a set of constraints and primitives that enable applications to be local-first, privacy-respecting, and interoperable. This page documents the conceptual model, core components, data formats, sync model, and the pragmatic tradeoffs we accept as the project evolves.
Conceptual Model
At its core, Epheme treats the user's device as a first-class runtime and authority. Applications are collections of signed, append-only objects that can be stored locally, optionally replicated to trusted hubs, and synchronized with peers under explicit user control.
Core Components
- Epheme Core (library): utilities for stable device identity, signing, object formats, and sync primitives.
- Device Runtime: local execution environment (browser or native) where primary state resides.
- Hubs (optional): light-weight services that provide discovery, persistence, and peer relay — never mandatory for functionality.
- Replication Layer: CRDT-friendly append-only logs or OT/patch streams with signed attestations for provenance.
- Attestations & Keys: short-lived capability tokens or signed statements — avoid long-lived PII-linked credentials.
Data Formats
Simplicity and auditability guide our choice of formats:
- JSON for human-readable objects with stable schemas.
- Signed envelopes for every object: { payload, meta, signer, signature } to prove origin and integrity.
- Append-only logs for operations with deterministic merging rules.
Sync Model & Conflict Resolution
Synchronization is optional and layered:
- Local-first: app continues to function offline with local authoritative state.
- Hub replication: devices may choose to push/pull signed objects to one or more trusted hubs.
- Peer sync: direct device-to-device replication via ephemeral channels or invited peers.
Conflicts are resolved with a combination of CRDTs for commutative data, last-writer-sane-timestamp for simple fields, and explicit human merge for complex edits.
Security & Privacy
- Device keys are generated and stored locally; hubs do not own user keys.
- Attestations are minimal and short-lived where possible.
- We avoid long-term identifiers and never collect PII by default.
APIs & Integration Points
Surface a small set of primitives in `@epheme/core`:
- `getStableId()` — device identity helper
- `signObject(obj)` / `verify(obj)` — signing primitives
- `appendLog(entry)` / `pullLog()` — replication primitives
- Lightweight HTTP relay endpoints for hubs (push/pull semantics)
Roadmap (evolving)
- V0: Core primitives + local-first demo apps.
- V1: Hub reference implementation and replication tests.
- V2: Cross-device discoverability and optional federation UX.
- V3: Polished APIs, policy tools, and community adapters.
Tradeoffs
Choosing Epheme’s constraints means accepting limits:
- We trade centralized analytics for user privacy.
- Cross-device UX requires replication strategies that may be more complex than single-server SaaS.
- We prioritize durability and provenance over raw storage convenience.
How This Page Evolves
This page is a living document — as prototypes reveal practical concerns, APIs and formats will adapt. The Dev Journal and repository issues will track design decisions and experiments.