Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 79 additions & 41 deletions apps/documentation/src/content/docs/architecture/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,49 +18,85 @@ today, and what must stay true_.
## The package graph

Nine packages and three apps. Dependencies point in one direction only — no
package imports something that imports it back.
package imports something that imports it back. Each box depends only on boxes
above it; the annotations next to each box say which ones.

```
┌────────────┐
│ schema │ Zod contracts. Depends on nothing.
└─────┬──────┘
│
┌─────▼──────┐
│ core │ Project logic: load, resolve, write.
└─────┬──────┘ Fully synchronous.
┌───────────────┼───────────────┐
│ │ │
┌─────▼────┐ ┌─────▼────┐ ┌─────▼────┐
│ server │ │ mcp │ │ editor │
│ (Hono) │ │ (agents) │ │ (React) │
└─────┬────┘ └─────┬────┘ └─────┬────┘
│ │ │
└───────────────┼───────────────┘
│
┌─────▼──────┐
│ apps/cli │ The composition root. The only thing
└────────────┘ that knows every other piece exists.

┌────────────┐ Consumed by mcp and cli. Depends on no workspace
│ generate │ package at all — which is why it could be migrated
└────────────┘ to Effect in isolation.

tokens · tui · config Leaves. CSS tokens, terminal rendering,
shared tsconfig.
┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐
│ schema │ │ tokens │ │ tui │ │ config │
│ (Zod) │ │ (CSS) │ │ │ │ │
└────┬─────┘ └──────────┘ └────────┘ └──────────┘
│ Leaves: none of these four depends on a workspace package.
┌────▼─────┐
│ core │ core → schema
└────┬─────┘ Fully synchronous. Node-bound today: it imports node:fs,
│ node:path and node:crypto.
┌─────┴─────────────┐
│ │
┌──▼───────┐ ┌────▼─────┐
│ server │ │ generate │ server → core, schema (no node: imports)
│ (Hono) │ │ (Effect) │ generate → core, schema
└──┬───────┘ └────┬─────┘
│ ┌────┴──────────┐
│ ┌────▼────┐ ┌────▼────┐
│ │ mcp │ │ editor │ mcp → core, generate, schema
│ │ (agents)│ │ (React) │ editor → core (events), generate
│ └────┬────┘ └────┬────┘ (examples), schema, tokens
│ │ │
┌──▼──────────────▼───────────────▼──┐
│ apps/cli │ cli → core, schema, server, generate,
└────────────────────────────────────┘ mcp, editor, tui
```

| Package | Source lines | Role |
| ---------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
| `@laqi/schema` | 149 | Zod contracts for mock files, config and state. The vocabulary everything else speaks |
| `@laqi/core` | 1,314 | Loading, state resolution, atomic writes. Fully synchronous, `ProjectResult<T>` as its error channel |
| `@laqi/generate` | 1,290 | Types ⇄ data: parse TypeScript, infer from JSON, generate mocks, print types. Effect-first internally |
| `@laqi/server` | 754 | The mock server, the control plane and the public app, on Hono |
| `@laqi/mcp` | 679 | The agent-facing tool surface |
| `@laqi/editor` | 2,236 | The control panel — a plain React SPA |
| `@laqi/tui` | 341 | Terminal rendering: layout, palette, screens |
| `@laqi/tokens` | — | Design tokens as CSS, shared by the panel and the site |
| `@laqi/config` | — | Shared tsconfig base |
| `apps/cli` | 2,831 | The `laqi` binary. Owns the process and composes everything |
Lines show the layering; the annotations and the edge list below give the exact
dependencies. `apps/cli` loads `generate` and `mcp` with dynamic `import()`.

`apps/site` depends on `tokens`, and `examples/todo-app` depends on the `laqi`
binary (`apps/cli`). `apps/documentation` depends on no workspace package.

The list below is the same graph as data, one `dependent -> dependency` edge per
line, named by directory. `scripts/docs/architecture-graph.test.ts` derives the
real edges from every workspace `package.json` and fails when this list
differs, in either direction. When a dependency changes, change one line here.

<!-- graph:edges -->

```
cli -> core
cli -> editor
cli -> generate
cli -> mcp
cli -> schema
cli -> server
cli -> tui
core -> schema
editor -> core
editor -> generate
editor -> schema
editor -> tokens
generate -> core
generate -> schema
mcp -> core
mcp -> generate
mcp -> schema
server -> core
server -> schema
site -> tokens
todo-app -> cli
```

| Package | Source lines | Role |
| ---------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@laqi/schema` | 149 | Zod contracts for mock files, config and state. The vocabulary everything else speaks |
| `@laqi/core` | 1,314 | Loading, state resolution, atomic writes. Fully synchronous, `ProjectResult<T>` as its error channel. Imports `node:fs`, `node:path` and `node:crypto`, so it runs on Node and Bun only |
| `@laqi/generate` | 1,290 | Types ⇄ data: parse TypeScript, infer from JSON, generate mocks, print types. Effect-first internally |
| `@laqi/server` | 754 | The mock server, the control plane and the public app, on Hono |
| `@laqi/mcp` | 679 | The agent-facing tool surface |
| `@laqi/editor` | 2,236 | The control panel — a plain React SPA |
| `@laqi/tui` | 341 | Terminal rendering: layout, palette, screens |
| `@laqi/tokens` | — | Design tokens as CSS, shared by the panel and the site |
| `@laqi/config` | — | Shared tsconfig base |
| `apps/cli` | 2,831 | The `laqi` binary. Owns the process and composes everything |

## What actually ships

Expand All @@ -86,8 +122,10 @@ Two consequences worth holding on to:
Rules that hold across packages. Breaking one is a bug, not a style choice.

**The composition root is `apps/cli`.** It is the only place that knows about
every package. Nothing below it reaches sideways: `@laqi/server` does not import
`@laqi/mcp`, and neither imports the other's internals.
every package. Between the packages below it, only the edges in the list above
exist: `@laqi/server` does not import `@laqi/mcp` or `@laqi/editor`, and no
package imports `apps/cli`. `@laqi/generate` is shared on purpose — `mcp` and
`editor` both build on it — so it sits below them rather than beside them.

**Heavy dependencies load lazily.** `typescript` (23 MB), `quicktype-core` and
`@faker-js/faker` are behind dynamic `import()`, so starting a mock server never
Expand Down
18 changes: 18 additions & 0 deletions apps/documentation/src/content/docs/decisions/0005-monorepo.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,24 @@ title: ADR-0005 — Monorepo aligned with rakoi
**Status:** Accepted
**Date:** 2026-08-24

> **Note, 2026-10-24.** The decision below is unchanged; this records where the
> code stands against it.
>
> - **`core` is Node-bound today.** Its loader, writer, project, state store,
> revision, canonical-JSON and atomic-file modules import `node:fs`,
> `node:path` or `node:crypto`. Only `server` is free of `node:` imports.
> "`core` + `server` run the same on Node and on the edge" is therefore not
> true yet: `server` could run on a Worker, `core` cannot.
> - **`apps/relay` does not exist.** [ADR-0007](/decisions/0007-public-url/)
> defers the relay to phase 2, so the diagram's `relay` entry is planned, not
> built.
> - **The relay needs a storage port in `core` first.** `core` would have to
> take its file and hash access through an interface that a Worker can
> implement before the relay can reuse it. That port is not implemented.
>
> The package graph as it is now lives in
> [Architecture](/architecture/#the-package-graph).

## Context

v1 was a flat npm package of four files. v2 has at least four distinct
Expand Down
105 changes: 105 additions & 0 deletions scripts/docs/architecture-graph.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
import { existsSync, readFileSync, readdirSync } from 'node:fs'
import { join } from 'node:path'
import { describe, expect, it } from 'vitest'

// The architecture page drew a package graph by hand and then claimed things
// about it that the manifests disprove: "generate depends on no workspace
// package at all" while it depends on core and schema, and "nothing below the
// CLI reaches sideways" while editor and mcp both import generate. Nothing
// compared the page with the code, so the drawing aged on its own.
//
// The page keeps its edge list in one machine-readable block, introduced by
// the marker below. This test derives the real list from every workspace
// package.json and fails when the two differ, in either direction.

const ROOT = join(import.meta.dirname, '..', '..')
const PAGE = join(ROOT, 'apps/documentation/src/content/docs/architecture/index.md')
const MARKER = '<!-- graph:edges -->'
const DEPENDENCY_FIELDS = [
'dependencies',
'devDependencies',
'peerDependencies',
'optionalDependencies',
] as const

interface Manifest {
name: string
dependencies?: Record<string, string>
devDependencies?: Record<string, string>
peerDependencies?: Record<string, string>
optionalDependencies?: Record<string, string>
}

/** `apps/cli` is `cli`, `packages/core` is `core`: the directory names the node. */
function workspaceManifests(): Map<string, Manifest> {
const rootManifest = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')) as {
workspaces: { packages: string[] }
}
const manifests = new Map<string, Manifest>()
for (const pattern of rootManifest.workspaces.packages) {
const parent = pattern.replace(/\/\*$/, '')
for (const entry of readdirSync(join(ROOT, parent), { withFileTypes: true })) {
const manifestPath = join(ROOT, parent, entry.name, 'package.json')
if (!entry.isDirectory() || !existsSync(manifestPath)) continue
manifests.set(entry.name, JSON.parse(readFileSync(manifestPath, 'utf8')) as Manifest)
}
}
return manifests
}

function realEdges(manifests: Map<string, Manifest>): string[] {
const nodeOf = new Map([...manifests].map(([node, manifest]) => [manifest.name, node]))
const edges = new Set<string>()
for (const [from, manifest] of manifests) {
for (const field of DEPENDENCY_FIELDS) {
for (const dependency of Object.keys(manifest[field] ?? {})) {
const to = nodeOf.get(dependency)
if (to) edges.add(`${from} -> ${to}`)
}
}
}
return [...edges].sort()

Check warning on line 61 in scripts/docs/architecture-graph.test.ts

View workflow job for this annotation

GitHub Actions / Validate

unicorn(no-array-sort)

scripts/docs/architecture-graph.test.ts:61:21: Use `Array#toSorted()` instead of `Array#sort()`.
}

function documentedEdges(): string[] {
const page = readFileSync(PAGE, 'utf8')
const start = page.indexOf(MARKER)
if (start === -1) return []
const block = /```[^\n]*\n([\s\S]*?)```/.exec(page.slice(start + MARKER.length))
if (!block) return []
return (block[1] ?? '')
.split('\n')
.map((line) => line.trim())
.filter(Boolean)
.sort()

Check warning on line 74 in scripts/docs/architecture-graph.test.ts

View workflow job for this annotation

GitHub Actions / Validate

unicorn(no-array-sort)

scripts/docs/architecture-graph.test.ts:74:6: Use `Array#toSorted()` instead of `Array#sort()`.
}

describe('architecture page package graph', () => {
const manifests = workspaceManifests()
const real = realEdges(manifests)

it('reads the workspace it claims to describe', () => {
expect(real).toContain('cli -> core')
expect(real).toContain('core -> schema')
})

it('lists exactly the workspace dependencies the manifests declare', () => {
expect(documentedEdges()).toEqual(real)
})

it('has no dependency cycle, as the page promises', () => {
const targets = new Map<string, string[]>()
for (const edge of real) {
const [from = '', to = ''] = edge.split(' -> ')
targets.set(from, [...(targets.get(from) ?? []), to])
}
const finished = new Set<string>()
const visit = (node: string, path: string[]): void => {
expect(path, `cycle: ${[...path, node].join(' -> ')}`).not.toContain(node)
if (finished.has(node)) return
for (const next of targets.get(node) ?? []) visit(next, [...path, node])
finished.add(node)
}
for (const node of manifests.keys()) visit(node, [])
})
})
Loading