Aquarius

A mermaid-flavored language and runtime for architecture diagrams — purpose-built, round-trip-safe, and editor-friendly.

Aquarius gives architecture diagrams what mermaid architecture-beta can't: a typed IR, first-class containment and reference slots, stable IDs, layout hints, and lossless source ↔ IR round-tripping. It still emits standard mermaid so existing tooling (docs, agents, renderers) keeps working.

[!NOTE] Scope guarantee. Architecture is the entire domain. Sequence, state, flowchart, class, ERD, Dockerfile, and React-state visualizations are explicitly out of scope and will not be added. This is the trade Aquarius makes for round-trip fidelity.

Install

pnpm add @tyler-reagan/aquarius
# or: npm install / yarn add

Zero runtime dependencies. ESM + CJS + .d.ts.

Quick start

import { parse, validate, lower, BUILT_IN_REGISTRY } from '@tyler-reagan/aquarius';

const source = `aquarius architecture v0.1

vpc prod "Production VPC" {
  subnet web "Web Tier" {
    ec2 api "API server" { instanceType = "t3.medium" }
  }
  subnet data "Data Tier" {
    rds db "Postgres" { engine = "postgres" }
  }
}

api -[calls]-> db
`;

const { diagram, diagnostics } = parse(source);
if (!diagram) throw new Error(diagnostics[0].message);

// Semantic validation against the merged built-in registry
const issues = validate(diagram, { registry: BUILT_IN_REGISTRY });
console.log(issues); // []

// Lower to mermaid for rendering / docs / agents
console.log(lower(diagram));
// architecture-beta
//
//   group prod(cloud)[Production VPC]
//   group data(cloud)[Data Tier] in prod
//   service db(database)[Postgres] in data
//   group web(cloud)[Web Tier] in prod
//   service api(server)[API server] in web
//
//   api:R --> L:db

The grammar shape is kind id "label" { props… nested-nodes… }. Edges use a separate top-level form (source -[kind]-> target). Containment is physical (block nesting); semantic references between nodes use @ref-slot = id inside a node block.

The round-trip contract is property-tested at 1000+ cases per CI run: canonicalize(parse(emit(d))) === canonicalize(d).

What's in the box

| Module | Function | What it does | |---|---|---| | parse | (source) → { diagram, diagnostics } | .aqua source → IR | | emit | (diagram) → source | IR → canonical .aqua source | | validate | (diagram, { registry }) → diagnostics[] | Containment, refs, kinds, edge endpoints, ID uniqueness | | lower | (diagram) → string | IR → mermaid architecture-beta | | lift | (source) → diagram | mermaid architecture-beta → IR | | repair | (source) → { source, applied } | Idempotent source fixups (BOM, CRLF, header) | | suggestKinds | (query, registry) → suggestions[] | Levenshtein-based "did you mean…?" for AQ-101 |

Plus the IR types (AquariusDiagram, AquariusNode, AquariusEdge, AquariusRef, AquariusLayout, AquariusTrivia, AquariusDiagnostic), walkers (walk, findNode, getChildren, indexNodesById, …), and three built-in kind packs (generic, aws, k8s) with ~60 architecture kinds.

Full signatures and exports: see src/index.ts or the generated .d.ts in the published package.

Design

Aquarius is a pure library with zero runtime UI dependencies. The boundary is enforced at build time by dependency-cruiser — see .dependency-cruiser.cjs. The IR is the single contract; source text and JSON are two serializations of the same shape, both round-trip-safe.

| Deeper material | Where | |---|---| | Language specification (lexical + block grammar, EBNF) | docs/SPEC.md | | Canonical JSON IR + round-trip invariants | docs/IR.md | | Interop with mermaid architecture-beta (lossy fields, agent prompts) | docs/COMPATIBILITY.md | | Phased delivery, scope boundaries | docs/ROADMAP.md | | MCP-protocol direction-of-travel | docs/MCP_FUTURE.md | | Phase-1 implementation plan (historical) | Planisphere docs/history/PLAN.md |

Consumers

Aquarius is consumed today by Planisphere — an interactive architecture-diagram editor whose canonical store state is an AquariusDiagram. Long-term, Aquarius is the protocol-level diagram representation flowing between MCP hosts and host-rendered editors.

Development

pnpm install
pnpm typecheck   # tsc --noEmit
pnpm test        # vitest run (includes the 1000-case round-trip property test)
pnpm depcruise   # extraction-readiness boundary check
pnpm build       # tsup → ESM + CJS + .d.ts
pnpm lint        # typecheck + depcruise

Releases are tag-driven: push vX.Y.Z, the workflow drafts a GitHub Release from docs/releases/vX.Y.Z.md and publishes to npm via OIDC trusted publishing. See docs/releases/README.md.