Epicenter Documentation

The Epicenter API is a Cloudflare Worker deployment that handles authentication, real-time sync, AI inference, and billing for the hosted personal cloud product. It is composed of a Hono-based worker (worker/) and a SvelteKit dashboard SPA (ui/).

Key responsibilities include:

• Authentication: Managed via Better Auth (supporting Google, GitHub, and Microsoft social sign-in).
• Real-time Sync: Uses Cloudflare Durable Objects to manage Yjs document sync rooms via WebSockets or HTTP.
• AI Inference: Provides AI streaming (OpenAI and Gemini) via @tanstack/ai.
• Identity: Resolves Better Auth users as principals for document partitioning.

Tab Manager distinguishes between two types of state to avoid conflicts with the browser:

1. Browser State (Ephemeral): Mirrors the current reality of Chrome (open windows and tabs). It is managed via chrome.windows.getAll and event listeners. This state is not persisted and includes actions like close, activate, pin, mute, reload, and duplicate.
2. Workspace State (Persistent): Contains saved tabs, bookmarks, chat history, and tool trust settings. This state is managed by @epicenter/workspace, persists to IndexedDB, and syncs across devices via WebSockets.

The UI is a Svelte application running in a Chrome Side Panel, avoiding the use of popups or content scripts.

The apps/api server is transitioning from a Cloudflare-only deployment to a runtime-agnostic design. This allows the same codebase to run as a Cloudflare Worker or as a self-hosted Bun/Node process.

Key architectural changes include:

• Room Logic: The core Room logic (Yjs sync, update log, presence, dispatch) is being moved to src/room/core.ts to be independent of the runtime.
• Abstraction Layers: Cloudflare-specific services (Durable Objects, R2, KV) are being placed behind Epicenter-owned contracts with two backends: a Cloudflare backend and a Bun/Node backend.
• Entry Points:
  • src/worker.ts: The Cloudflare entry point (default).
  • src/server.ts: The Bun entry point for self-hosting.

The Skills Editor is a local editor used to author prompt files and configurations for Epicenter agents. It allows you to create 'skills'—sets of markdown instructions and reference files that guide agent behavior.

Key characteristics:

• Local-only: Your skills stay on your machine; no remote sync is implemented.
• Collaborative-ready: Uses Yjs CRDTs under the hood, meaning undo/redo works across sessions and edits are conflict-free, even if multiple sessions are open locally.
• Offline-first: Works entirely offline using IndexedDB.

The docs/ directory is organized into the following functional areas:

• /articles: Technical write-ups on specific concepts or implementations.
• /architecture: High-level system diagrams and architectural documentation.
• /blog: Long-form content and blog posts.
• /guides: Task-specific how-to guides and integration instructions.
• /patterns: Documented coding patterns and best practices.
• /assets: Static resources like images and demos.
• /launches: Launch campaign materials.
• /release-notes: Version release notes.
• /adr: Architecture Decision Records (ADRs).

The remote storage system is divided into four distinct layers with specific responsibilities:

1. Client App: Manages the local Y.Doc, local IndexedDB updates, a remote-sync-disabled flag, and the last accepted remote generation.
2. API Worker: Handles Better Auth session checks, derives userId and doName, and acts as a registry gate to allow only authorized sync requests.
3. Durable Object Room: Manages the in-memory Y.Doc, Awareness, active WebSockets, and persistent storage (updates table, snapshots table, and SQLite byte measurement).
4. Postgres Registry: Maintains the source of truth for room metadata, including userId, doType, resourceName, doName, status, generation, and storageBytes.

Epicenter uses a two-tier architecture for its distributed sync system. Clients (Single Page Applications) connect to a Remote Server (apps/api) which manages authentication (via Better Auth), AI streaming (/ai/chat), and acts as a Yjs relay.

Key Connectivity Rules:

• Client ──► Remote Server: Allowed via WebSocket and HTTP for data sync, presence, AI, and auth.
• Server ──► Server: Allowed via WebSocket.
• Direct Connections: Connections can only be made to servers. Clients cannot accept incoming connections.

Note: The previously planned local sidecar tier has been removed. Presence currently reports liveness only.

Epicenter uses a leaderless, bidirectional graph topology for syncing data across devices. The architecture follows a hub-and-spoke with mesh pattern:

• Clients (Browsers): Connect to servers but cannot accept incoming connections. They use OPFS (Origin Private File System) for storage.
• Servers (Bun/Node): Can both accept connections from clients and initiate connections to other servers (forming a mesh). They use the filesystem for storage and can serve blobs.

Connection Rules:

• Client ──► Server: ✅ (WebSocket)
• Client ──► Client: ❌ (Not supported)
• Server ──► Server: ✅ (WebSocket, for server-to-server sync)
• Server ──► Client: ❌ (Not supported)

Epicenter uses a split distribution model to separate stable contracts from environment-specific recipes:

1. Schema (npm): Published as a single root export per app (e.g., @epicenter/honeycrisp). This contains tables, action types, branded IDs, and awareness definitions. This is a versioned contract that must remain compatible for sync.
2. Browser Binding (App Code): Stays private within the SvelteKit app. It is not exported to npm.
3. Runtime Recipes (jsrepo): Scripts and Daemons are distributed as jsrepo blocks. Consumers copy these into their own trees and edit them to suit their specific environment (e.g., custom auth, sync URLs, or log paths).

Key Principle: Primitives and Contracts are on npm; Recipes are on jsrepo.