49 lines
2.5 KiB
Markdown
49 lines
2.5 KiB
Markdown
---
|
|
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.
|