Forge is one local-first system shared by the web app, API, agents, and companion.

This page explains the architecture behind Forge so readers can understand how the product stays coherent across interfaces, stores structured data locally first, and keeps its docs aligned with the running system.

Runtime Surfaces

These are the product surfaces users and tools actually interact with.

Web application

The user-facing app is mounted under /forge/. The UI includes execution, calendar, notes, wiki, health, preferences, and Psyche surfaces.

HTTP API

The versioned API is mounted under /api/v1/. The generated OpenAPI 3.1 document is served from /api/v1/openapi.json.

Agent adapters

OpenClaw, Hermes, and Codex do not mirror the entire internal API. They expose curated operator, mutation, and UI-handoff surfaces on top of the same Forge model.

Stack

This is the stack currently powering the product.

Concern	Technology	Why it matters here
UI	React 19, TypeScript 5.8, Vite 6, Tailwind CSS 4	SPA served from the same repo, with local and mounted runtime paths.
Backend	Fastify 5, TypeScript, custom OpenAPI generator	One server process exposes runtime API, auth bootstrap, and OpenAPI JSON.
Persistence	SQLite, structured JSON columns, SQLite-backed wiki storage	Execution and reflection records stay local-first and auditable.
Desktop / native	Tauri 2, Swift iOS companion, Rust Iroh bridge	Desktop shell, HealthKit import, and default Iroh/QUIC companion pairing are separate runtime surfaces.
Mobile transport	Iroh, QUIC, ALPN `forge-companion/1`, length-prefixed JSON frames	Forge Companion dials the desktop by Iroh node id and falls back to manual HTTP only when explicitly requested.
Documentation	GitHub Pages static docs + generated OpenAPI reference	The public guide and API explorer stay published side by side.

Companion Transport

The iPhone path is Forge-owned Iroh and QUIC, not a generic HTTPS tunnel.

Desktop host

Fastify starts forge-companion-iroh host from a prebuilt package binary, a configured FORGE_COMPANION_IROH_BIN, or the Rust source fallback. The host keeps its state under the Forge data root, reports a ready JSON payload, and proxies accepted requests into http://127.0.0.1:4317.

iOS bridge

The Swift app links the same Rust crate as a static library, parses the Iroh QR, registers the forge-iroh:// scheme for the embedded web view, and sends mobile API calls over authenticated QUIC streams.

Protocol boundary

Forge uses ALPN forge-companion/1. The first frame validates the QR token, and later frames carry Forge HTTP request and response envelopes. The app does not use alleycat/1.

Longer reference

The dedicated transport page contains the relay model, pairing payload, request envelope shape, fallback path, licensing notes, and verification commands.

Read transport details

Storage And Data Model

Forge combines structured operational data with long-form knowledge.

Structured runtime records

Goals, strategies, projects, work items, task runs, habits, calendar records, preferences, Psyche entities, questionnaires, sleep, workouts, and notes are stored in SQLite with typed repository boundaries.

SQLite-backed wiki memory

Wiki pages keep Markdown content in SQLite notes rows. Forge stores page metadata, ingest jobs, links, and search index state in the database.

Multi-user ownership

Most entity families support explicit userId ownership for human and bot actors. Forge's project-management surfaces also support one owner plus one-or-many assignees. Read flows may widen scope with repeated userIds.

Hierarchy-aware execution

Forge keeps goal, strategy, and project as first-class records, then models issue, task, and subtask through one lean work-item layer with AI instructions, execution mode, acceptance criteria, blocker links, completion reports, and canonical git refs.

Shared PM surfaces

The web app exposes one mixed board for projects, issues, tasks, and subtasks plus one compact hierarchy tree with shared filters, level visibility, ownership filters, and guided modal linking flows.

Local-first by default

The repo runtime, OpenClaw plugin, and Hermes plugin can all point at one shared local data root. That is the expected shape for a shared Forge system.

Route Families

The API is grouped by product area so the system stays legible.

Family	Root	Coverage
Execution	`/api/v1/goals`, `/projects`, `/tasks`, `/work-items`	Goals, strategies, projects, issues, tasks, subtasks, task runs, adjustments, activity, metrics, and reviews.
Calendar	`/api/v1/calendar/*`	Connections, mirrored events, work blocks, timeboxes, and native events.
Knowledge	`/api/v1/wiki/*`, `/api/v1/notes`	Wiki pages, ingest, search, embeddings, and Markdown evidence records.
Preferences	`/api/v1/preferences/*`	Contexts, concept lists, items, judgments, signals, and score updates.
Psyche	`/api/v1/psyche/*`	Values, patterns, behaviors, beliefs, modes, reports, questionnaires, and self-observation.
Health	`/api/v1/health/*`	Sleep, sports, workouts, and iPhone companion sync/update flows.
Platform	`/api/v1/settings`, `/entities/`, `/agents/`	Settings, batch entity mutation, approvals, agents, users, and onboarding.

Repository Layout

These folders carry the main product responsibilities.

Path	Purpose
`src/`	React app routes, components, view logic, API client, and UI state.
`server/src/`	Fastify app, repositories, managers, OpenAPI builder, and tests.
`docs/`	Longer technical guides and operating notes.
`openclaw-plugin/`	Published OpenClaw package and GitHub Pages output boundary.
`plugins/forge-hermes/`	Hermes plugin package.
`plugins/forge-codex/`	Codex adapter and runtime payload used for in-repo agent work.
`ios-companion/`	Swift iPhone companion for pairing and HealthKit import.
`companion-iroh/`	Forge-owned Rust Iroh transport host and iOS static library for ALPN `forge-companion/1`.
`src-tauri/`	Tauri desktop shell integration.

The API reference at `/api/` is generated from the same OpenAPI source that the running Forge server exposes at /api/v1/openapi.json, so the public docs stay aligned with the real product contract.