How Avodado is built — a pure core library, with everything else as a consumer of it.

This page is for the curious and for contributors. You don't need it to use Avodado. The full version lives in ARCHITECTURE.md in the repo.

The one principle

The files on disk are the only source of truth. The CLI, the studio, and AI agents are all just editors and consumers of your .md files — none of them owns any state. The core library turns files into a validated model; everything else consumes that model.

The packages

Avodado is a monorepo where every dependency points inward to a pure core:

@avodado/core   ← pure: parse, schemas (87 blocks), validate, resolve, edit ops. No I/O.
@avodado/render ← core. Emits HTML strings. No DOM, no browser. Themes.
@avodado/export ← core + render. HTML and PDF output (Playwright).
@avodado/sync   ← core. Imports external sources (OpenAPI, CSV).
@avodado/studio ← core + render. The browser editor, shipped as static assets.
@avodado/mcp    ← core + render + sync. The MCP server.
avodado         ← everything above. The CLI. The only layer that owns process.exit.

The rules:

@avodado/core does no I/O — no file system, no network, no DOM. Strings in, models and diagnostics out.
Libraries return diagnostics as values; they don't throw for expected problems. Only the CLI turns diagnostics into console output and exit codes.

The block registry

Every block type is registered in one place in @avodado/core:

export const blockSchemas = {
  meta, callout, table, sequence, erd, userstory, timeline, kanban,
  // … one entry per block type — 87 in total.
} as const satisfies Record<BlockType, ZodTypeAny>;

Renderers use the same Record<BlockType, …> pattern, so adding a block type is one schema plus one renderer — and the TypeScript compiler points at every place that needs updating. No scattered switch statements.

Rendering

@avodado/render emits self-contained HTML: styles are scoped under one class, SVG diagrams use integer coordinates so output is deterministic, and themes are pure CSS-variable overrides — which is why diagrams recolor with the text.

The studio

The studio runs the whole parse → validate → render pipeline in the browser. The avo studio server is only a small file bridge (localhost JSON read/write plus change events) — it never renders anything itself. Edits go through the core's edit operations, which rewrite individual blocks in place, keeping diffs small.

Quality

Strict TypeScript throughout, 650+ tests, and every published example on this site is rendered by the real pipeline at build time — the docs can't drift from the code.

Architecture