Architecture
How filepath works under the hood.
High-Level Architecture
filepath runs on Cloudflare's edge infrastructure:
- Cloudflare Workers — HTTP API, WebSocket handling, static assets
- Durable Objects (DO) — One ChatAgent DO per agent node
- D1 — SQLite database for sessions, nodes, users
- Cloudflare Sandbox — Container runtime for agent code
Data Flow
Browser <-> Worker (SvelteKit + API routes)
↓ WebSocket upgrade
Browser <-> ChatAgent DO (per agent node)
↓ fetch / stdin-stdout
ChatAgent DO <-> LLM API (OpenRouter)
↓ D1 queries
ChatAgent DO <-> D1 (node lookup, history)
Key Components
ChatAgent DO
One per agent node. Maintains WebSocket connection, message history, and calls LLM APIs. Not the "brain"—just a relay/conductor.
D1 Database
SQLite on the edge. Stores agent sessions, nodes, user data, conversation history. Self-referential tree via agentNode.parentId.
Worker
SvelteKit app on Cloudflare. Handles HTTP routes, serves UI, proxies WebSocket upgrade to DOs.
Sandbox (Future)
Cloudflare Sandbox for running containerized agents. Currently using direct LLM mode.
BYOK Model
Bring Your Own Key:
- Users provide their own LLM API keys
- Keys stored encrypted in D1 (AES-256-GCM)
- Account-level keys: stored on user table
- Per-session keys: stored on agent_session table
- Per-node override: passed when spawning
Scaling
- Workers scale automatically (edge-deployed)
- Each DO is single-threaded but durable (state persists)
- D1 scales reads well; writes are serialized per-region
- Agents don't share state—perfect for horizontal scaling