developer-guide/architecture/index.md

id	title	description	tags	lang
architecture	Architecture	The three applications and four packages, and how a request travels through them.	architecture overview	en

Architecture

f451 is a pnpm monorepo on Node 22. Three applications and four shared packages divide the work cleanly along one line: apps/api is the only place that checks permissions, runs the review workflow and writes to the index. Everything else either renders what the API gives it, or talks to the API on someone's behalf.

Request flow

Browser ──► apps/web (Next.js)  ──► apps/api (Fastify) ──► Forgejo / GitHub
                                          │                 (content, permissions)
                                          └──► PostgreSQL   (index, sessions)

AI agent ──► apps/mcp (MCP↔HTTP) ──────────► apps/api (same HTTP API)

Nothing skips apps/api. The web app never talks to Git directly, and the MCP service never talks to Postgres or Git directly — both reach content and permissions exclusively through the API's HTTP surface.

The three applications

App	Role
apps/api (Fastify)	Indexing, read and write endpoints, webhooks, drift reconciliation, admin. The only place with permission checks, the review workflow and the index.
apps/web (Next.js App Router)	The user interface. Proxies /api, /auth, /admin, /media to the API, /drawio to the draw.io container, /mcp to the MCP service. Server Components by default; client islands stay small.
apps/mcp	Access for AI agents: a stateless translator between MCP and the HTTP API. It wraps only the HTTP API, holds no secret of its own, and passes the calling user's token through on every request.

The four packages

Package	Role
packages/markdown	Renders Markdown to sanitized HTML. Shared by reading and writing so both sides agree on what a construct means.
packages/editor	The ProseMirror schema behind the WYSIWYG editor. Round-trip tests with packages/markdown keep reading and editing aligned — a document that survives Markdown → editor → Markdown unchanged.
packages/design-tokens	The catalog of design tokens that drives the look and feel — see web-frontend.
packages/git-provider	One interface, two implementations (Forgejo, GitHub): read/write files, commits, branches, pull requests, reviews.

See principles for why the lines are drawn exactly here, and repository-layout for the directories underneath each of these.