# 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

- **[Creating Acequia Apps](creating-acequia-apps.md)** — Step-by-step guide to building an Acequia app: directory structure, initialization, route registration, and peer communication.

- **[App Patterns & Architecture](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](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](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](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](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

- **[Service Worker](service-worker.md)** — The Acequia service worker (`sw.js`): fetch interception, route registry, transport selection, caching, and virtual filesystem mounts.

- **[Discovery Server](discovery-server.md)** — The localDiscovery server: peer discovery, route registration, WebSocket protocol, and HTTP-to-WebSocket proxying.

- **[Virtual Filesystem](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](user-authentication.md)** — The three-mode JWT authentication system: chain tokens (capability delegation), user tokens (direct auth), and legacy device tokens.

## APIs & Specifications

- **[API Reference](api-reference.md)** — Concise reference for Acequia's public JavaScript APIs: module initialization, identity, groups, and messaging.

- **[State API Spec](state-api-spec.md)** — RESTful API pattern for managing distributed application state with resource-oriented design and pub/sub notifications.

- **[Settings Architecture](settings-architecture.md)** — Architecture for remote control and state management, distinguishing persistent settings from one-time commands.

- **[Runtime Contexts](runtime-contexts.md)** — Support for multiple JavaScript runtimes (browser, service worker, web worker, Node.js, Deno) with context detection and per-environment capabilities.
