Demo content from demo/developer-guide (0c17989)

architecture/index.md

@@ -0,0 +1,49 @@
+---
+id: architecture
+title: Architecture
+description: The three applications and four packages, and how a request travels through them.
+tags: [architecture, overview]
+lang: 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.