**Artifact** from Bead: 96597c32 · [canonical source](https://redfish.acequia.io/guerin/.agents/96597c32-7f1c-4e95-acd5-635673461781/2026-05-16/artifacts/acequia-skills.md) · session 2026-05-16 · discussion: Talk: 96597c32
- **Source URL:** https://acequia.io/documentation/platform/index.md - **Fetched:** 2026-05-18 - **Captured by:** Claude Code (Opus 4.7, 1M context), via WebFetch - **Companion note:** [acequia-skills.md (notes/)](../notes/acequia-skills.md) — same summary + bead cross-references
## 5-sentence summary 1. **Acequia is a peer-to-peer communication framework** that routes data between browsers using three transports — postMessage, WebRTC, and HTTP proxy — making each browser a participating node in a federated network rather than a tenant on a platform. 2. **Each node composes three local services**: a **local WebDAV server** (Nephele on Express, with three-mode JWT auth — chain tokens for capability delegation, user tokens for direct auth, and legacy device tokens), a **service worker** that intercepts fetches and selects among the three transports, and a **local discovery server** with WebSocket protocol and HTTP-to-WebSocket proxying. 3. **Sovereignty primitives**: per-directory public access via `.acequia-access.json` sidecar files, capability delegation through verifiable **chain tokens** (the bearer-verifiable migration path from server-mediated authorization), and shared filesystems composed through mounts on the `/acq/` virtual filesystem with IndexedDB-stored mount tables. 4. **Higher-level coordination services**: **group shared state** (peer-elected state-leader pattern where any member updates state and the leader merges and broadcasts over WebRTC with WebSocket fallback) and a **group event bus** (decentralized pub/sub with wildcard topic matching, retained events with TTL, subscription advertisement, and dedup over full-mesh WebRTC). 5. **Apps deploy as static directories** with route registration, work across multiple JavaScript runtimes (browser, service worker, web worker, Node.js, Deno), and are the **operational instantiation of the [acequia manifesto](https://acequia.org/acequia-manifesto.md)** — edge-sovereign, commons-governed, browser-as-server, with the means of digital production in citizen hands.
## Full documentation index snapshot (verbatim from source URL) # Acequia Platform Documentation Acequia is a peer-to-peer communication framework that routes data between browsers using multiple transports (postMessage, WebRTC, HTTP proxy). These documents cover the platform architecture, APIs, and patterns for building acequia-powered applications.
## Getting Started - **[Getting Started Tutorial](https://acequia.io/documentation/platform/getting-started.md)** — Build your first Acequia app with peer communication in under 30 minutes - **[Creating Acequia Apps](https://acequia.io/documentation/platform/creating-acequia-apps.md)** — Step-by-step guide to building an Acequia app: directory structure, initialization, route registration, and peer communication. - **[App Patterns & Architecture](https://acequia.io/documentation/platform/creating-acequia-apps-patterns.md)** — In-depth patterns for Acequia app development: component architecture, styling, storage management, event systems, and error handling.
## Architecture - **[Architecture Overview](https://acequia.io/documentation/platform/architecture-overview.md)** — How Acequia routes data between browsers using three transport strategies, and the roles of the service worker, discovery server, and WebDAV server. - **[Acequia Object](https://acequia.io/documentation/platform/acequia-object.md)** — The Acequia system as a decentralized network of data and compute nodes, with browser-based and native node types, identity, and group membership. - **[Request Flows](https://acequia.io/documentation/platform/request-flows.md)** — How requests flow from initial fetch to final response, covering the three transport paths chosen by the service worker. - **[Registered Route Request Flows](https://acequia.io/documentation/platform/registered-route-request-flows.md)** — Detailed walkthrough of the three request paths for registered routes: direct HTTP, service worker local interception, and WebRTC proxy with fallback.
## Core Services - **[WebDAV Server](https://acequia.io/documentation/platform/webdav-server.md)** — The localWebDAV server: Nephele WebDAV on Express, JWT three-mode auth, scoped filesystem adapter, dotfile filtering, sidecar public access, cross-server COPY with TPC TransferHeader, and the full auth API surface. - **[Service Worker](https://acequia.io/documentation/platform/service-worker.md)** — "The Acequia service worker (`sw.js`): fetch interception, route registry, transport selection, caching, and virtual filesystem mounts." - **[Discovery Server](https://acequia.io/documentation/platform/discovery-server.md)** — The localDiscovery server: peer discovery, route registration, WebSocket protocol, and HTTP-to-WebSocket proxying. - **[Virtual Filesystem](https://acequia.io/documentation/platform/virtual-filesystem.md)** — The `/acq/` virtual filesystem: mount points, path rewriting, and transparent routing to remote WebDAV servers via IndexedDB-stored mounts.
## Authentication & Authorization - **[User Authentication](https://acequia.io/documentation/platform/user-authentication.md)** — "The three-mode JWT authentication system: chain tokens (capability delegation), user tokens (direct auth), and legacy device tokens."
## Project Design Documents Internal design documents for active development areas (in `documents/projects/`): - **[Capability Delegation](https://acequia.io/documentation/platform/projects/capability-delegation.md)** — Architecture for delegation chains, revocation, and the migration path from server-mediated to bearer-verifiable authorization. - **[Auth Status & Tracking](https://acequia.io/documentation/platform/projects/auth-status.md)** — Token type inventory, implementation parity matrix (localWebDAV vs BrowserDAV), phase tracker, and known gaps. - **[Public Access](https://acequia.io/documentation/platform/projects/public-access.md)** — `.acequia-access.json` sidecar files for per-directory anonymous read access, dotfile write-gated filtering, and approach analysis. - **[Filesystem Browser UI](https://acequia.io/documentation/platform/projects/filesystem-browser-ui.md)** — `<acequia-file-browser>` custom element: tree + list navigation, access indicators, sidecar editor, CRUD operations. - **[Group Shared State](https://acequia.io/documentation/platform/projects/group-shared-state-webrtc.md)** — "Peer-elected state leader pattern: any group member can update shared state, leader merges and broadcasts over WebRTC with WebSocket fallback." - **[Group Event Bus](https://acequia.io/documentation/platform/projects/group-event-bus.md)** — "Decentralized pub/sub over full-mesh WebRTC: fire-and-forget topic-based events with wildcard matching, retained events with TTL, subscription advertisement, and dedup." - **[WebDAV Cross-Server COPY](https://acequia.io/documentation/platform/projects/webdav-cross-server-copy.md)** — TPC TransferHeader protocol for server-to-server file transfer, streaming large files, recursive directory handling, and the cross-server middleware design. - **[Style Guide Adoption](https://acequia.io/documentation/platform/projects/style-guide-adoption.md)** — Single source of truth for design tokens (`acequia-tokens.css`), shared `system.css` component classes, and migration plan for system pages, web components, and acequia apps. - **[Light Theme](https://acequia.io/documentation/platform/projects/light-theme.md)** — Light theme token values, `data-theme` attribute switching, FOUC prevention, Shoelace integration, and style book philosophy updates. - **[Dashboard Redesign](https://acequia.io/documentation/platform/projects/dashboard-redesign.md)** — Domain-centric landing page: replace tab-based admin panel with card grid showing domain capabilities, retire redundant user-info page, align with acequia metaphor.
## APIs & Specifications - **[API Reference](https://acequia.io/documentation/platform/api-reference.md)** — Concise reference for Acequia's public JavaScript APIs: module initialization, identity, groups, and messaging. - **[State API Spec](https://acequia.io/documentation/platform/state-api-spec.md)** — "RESTful API pattern for managing distributed application state with resource-oriented design and pub/sub notifications." - **[Settings Architecture](https://acequia.io/documentation/platform/settings-architecture.md)** — Architecture for remote control and state management, distinguishing persistent settings from one-time commands. - **[Runtime Contexts](https://acequia.io/documentation/platform/runtime-contexts.md)** — Support for multiple JavaScript runtimes (browser, service worker, web worker, Node.js, Deno) with context detection and per-environment capabilities.