System Architecture

How SurfDoc is built — from the parser to the workspace to the clients.

Overview

SurfDoc is a typed document format and workspace. Five principles guide every architectural decision.

SurfDoc Architecture Overview SurfDoc Open Format Typed Blocks Multi-target Zero-Knowledge Auth AI-Native Every component shares these five principles

Layer Cake

Each layer is independent. surf-parse works without surf-server, and surf-server works without the Surf browser.

SurfDoc Layer Cake L5 Clients Surf Browser, WaveSite, doc.surf web L4 surf-server Axum workspace, API, rendering L3 OPAQUE-KE Auth Zero-knowledge password authentication L2 Surf Protocol (experimental) Document transport and sync (in development) L1 SurfDoc Format Typed blocks, front matter, multi-target L0 surf-parse Rust parser, 37 block types, 382 tests

Layer 0 (surf-parse) is the foundation. It compiles to native code and is embedded in every client via UniFFI or as a Rust dependency. Each higher layer adds functionality but never requires the layers above it.

Parse Pipeline

A .surf file goes through four stages: tokenize, parse, validate, and render. The pipeline is synchronous and deterministic.

SurfDoc Parse Pipeline .surf source Tokenize Parse Validate Render HTML / Terminal / Markdown / PDF

The render stage is pluggable. The same parsed document produces HTML for the web, ANSI for the terminal, Markdown for interop, and PDF for print.

Format Architecture

SurfDoc defines 37 typed block directives organized into 4 categories. Every block has a name, defined attributes, and rendering rules.

SurfDoc Format Architecture SurfDoc Blocks (37) Core (10) callout, code, data, decision, details, figure, metric, quote, summary, tasks Layout (4) columns, divider, section, tabs Web (13) cta, embed, faq, footer, form, gallery, hero-image, nav, page, pricing, site, style, testimonial Landing (10) before-after, comparison, features, hero, logo, pipeline, product-card, stats, steps, toc Every block is typed, validated, and rendered to multiple targets

The Web and Landing categories together contain 23 blocks, purpose-built for generating websites from SurfDoc files. This is the foundation of the phone-to-app pipeline.

Workspace Architecture

surf-server is the unified backend for SurfDoc. It serves the web UI, API, and handles authentication, document storage, and AI generation.

SurfDoc Workspace Architecture surf-server (Axum) Auth Notes Tasks Docs AI PostgreSQL Stripe SES Email LLM APIs All modules share one database and one binary

Authentication

SurfDoc uses OPAQUE-KE, a zero-knowledge password-authenticated key exchange. The server never sees or stores plaintext passwords.

SurfDoc Authentication Flow Client Server REGISTRATION Registration Start (blinded message) Server Response (evaluated element) Registration Finish (upload record) Registration Complete LOGIN Login Start (KE1 message) Server Response (KE2 message) Login Finish (KE3 message) JWT Access Token Server never sees passwords

After successful login, the server issues a signed JWT for session management.

Deployment

The SurfDoc workspace deploys as a single Rust binary on Fly.io with TLS termination at the edge proxy.

SurfDoc Deployment Architecture Cloud Infrastructure surf-server Rust/Axum binary (TLS at edge) PostgreSQL doc.surf Single binary, automated TLS, continuous deployment

Client Architecture

surf-parse is the shared core. Every client — web or native — uses the same Rust parser for rendering SurfDoc files.

SurfDoc Client Architecture surf-parse (Rust) Web Clients doc.surf — Axum SSR wave.site — Axum SSR cloudsurf.com — Axum SSR Native Clients Surf macOS — AppKit + WebKit + UniFFI Surf Linux — GTK4 WaveSite iOS — Swift + UniFFI One parser, many platforms — write once, render everywhere

AI System

SurfDoc uses a configurable multi-provider LLM system with admin-selectable providers. Three chat modes (Research, Plan, Build) produce different SurfDoc outputs.

SurfDoc AI System User Input Multi-Provider LLM Admin-configurable selection SurfDoc Output Research knowledge doc Plan spec doc Build implementation guide Three chat modes produce different SurfDoc document types

The AI is the controller in the Surf MVC architecture. It transforms natural language into typed SurfDoc blocks, which are then rendered by surf-parse.

Storage

SurfDoc uses PostgreSQL with a minimal, normalized schema. Application-enforced team and user scoping ensures users only access their own data.

SurfDoc Storage Architecture PostgreSQL Identity Users, auth, teams Documents Docs, folders, categories Tasks Items, status tracking AI Chat history, config Minimal schema, normalized, application-enforced access control

Each domain is independent. The identity layer handles OPAQUE-KE credentials and team membership. Documents and tasks are user-scoped with folder-based organization.