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, file-backed wiki storage	Execution and reflection records stay local-first and auditable.
Desktop / native	Tauri 2 and Swift iOS companion	Desktop shell and HealthKit import path are separate runtime surfaces.
Documentation	GitHub Pages static docs + generated OpenAPI reference	The public guide and API explorer stay published side by side.

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.

File-first wiki memory

Wiki pages remain Markdown-first and file-backed. Forge stores the page metadata, ingest jobs, and search index state while keeping the article source as files.

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.
`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.