Canonical short definitions live in _index.md §0.8. This file expands them with code references and adds terms that emerged after consolidation.

Last reviewed: 2026-05-24

Conventions

• Term — short definition (one sentence).
• Code: where in the repo the concept is defined / serialised.
• See: related ADRs, runbooks, or spec sections.

Core product model

Project

Top-level container owned by a user. Holds one workflow + many screens + optional connected git repo + shared library.

• Code: packages/db/src/schema.ts (opens in a new tab) → project
• API: POST /api/v1/projects, GET /api/v1/me/projects — see docs/api/rest.md (opens in a new tab)

Workflow

Directed graph of screens connected by edges. Live-synced via Yjs (Liveblocks Storage room project:${id}).

• Code: packages/db/src/schema.ts (opens in a new tab) → workflow; node/edge types in packages/shared/src/workflow.ts (opens in a new tab)
• Sync: Liveblocks Storage channel — see master spec §I.2.2
• See: ADR 0002

Screen

A composition of component instances. Node in the workflow graph.

• Code: ScreenData in packages/shared/src/workflow.ts (opens in a new tab)
• Storage: screen_composition table, one row per (projectId, screenId)

Edge

A connection between two screens, triggered by an interactive element. May reference a specific instance + event (navigate action).

• Code: WorkflowEdgeData in packages/shared/src/workflow.ts (opens in a new tab)

Component spec

Markdown file describing a component's contract — props, slots, events, structural sections. Source of truth for the component's interface.

• Format: YAML frontmatter + fenced <!-- arno:props v1 --> / <!-- arno:slots v1 --> blocks
• Code: parseComponentMd in packages/editor/src/md-parser.ts (opens in a new tab) → returns ParsedComponent
• Storage: raw MD in component_md_raw, immutable versions in component_md_versions

Component instance

A placement of a component within a screen, with concrete prop values and (optionally) children inserted into named slots.

• Code: ComponentInstance, findInstance, insertIntoSlot, removeById, updateProp in packages/shared/src/composition.ts (opens in a new tab)

Composition

The full tree of instances for one screen. Tree, not list — instances can hold children inside slots.

• Code: ScreenComposition in packages/shared/src/composition.ts (opens in a new tab)
• Store: CompositionStore class in packages/editor/src/composition-store.ts (opens in a new tab)

Slot

A named insertion point within a component, declared in its spec. Children of an instance live in instance.children[slotName] = [...].

• Code: insertIntoSlot in packages/shared/src/composition.ts (opens in a new tab)

Library

The set of component specs available to a project — either resolved from the connected git repo's design-system or from a built-in fallback.

• Code: LibraryStore in packages/editor/src/library-store.ts (opens in a new tab) — state machine fallback → cache → fetched
• See: ADR 0003

Prop schema

Typed declaration of a single prop on a component spec — string with textEditable flag, or enum with allowed values.

• Code: PropSchema, PropSchemaString, PropSchemaEnum in packages/shared/src/index.ts (opens in a new tab)

textEditable prop

Marker on a string prop indicating the Editor role may modify its value (without touching layout or component choice).

• See: master spec §I.1.2 (permission enforcement)

Rendering

Render adapter

The postMessage protocol + iframe bridge that lets a project's real React components render inside ARNO's preview pane without ARNO importing the bundle.

• Protocol: packages/render-adapter/src/ — ARNORenderMessage, ARNOReadyMessage, ARNONavigateMessage, PROTOCOL_VERSION
• See: ADR 0004

Bundle

The compiled output of a project's design system, hosted as a JS file the render adapter iframe loads. Each connected repo ships its own arno.entry.tsx.

• Convention: .github/workflows/arno-build.yml builds and publishes; URL configured per-project in connected_repo.bundle_hosting

Bundle proxy

ARNO backend route that serves bundles from private repos using the user's GitHub installation token (so private DS code doesn't leak to public CDN).

• See: master spec §I.3 ("Source of truth"), bundle hosting section

arno.entry.tsx

The entry file in a connected repo that registers the design-system components for the render adapter. Lives at repo root.

• Convention: documented in master spec §I.2.3

Live collaboration

Session-branch

Per-Maker working git branch (arno/{user-handle}). Where in-flight Yjs edits are eventually snapshotted to.

• Code: session_branch_state table in packages/db/src/schema.ts (opens in a new tab)

CRDT

Conflict-free Replicated Data Type. ARNO uses Yjs (via Liveblocks Storage) for workflow + presence. Component spec edits use REST + versioned storage, not CRDT.

• See: master spec §0.3 principle 10

Snapshot

A git-committed state derived from the live Yjs document. Activity-based: triggered after edit-quiescence, not on a fixed schedule.

• See: master spec §0.3 principle 5

Soft snapshot

In-memory cache of component versions captured at screen-edit-session start, so the screen renders consistently even if the underlying spec changes mid-edit.

• See: master spec §0.8

Quality & sync

Drift

A divergence between an MD component spec and the actual TSX implementation in the connected repo. Detected by .github/workflows/arno-check.yml and surfaced in ARNO UI.

• Code: component_drift table; sync logic in apps/api/src/sync.ts (opens in a new tab) and apps/api/src/github.ts (opens in a new tab)
• Storage: one row per (projectId, filePath), status enum
• See: master spec §0.3 principle 8

check_run

GitHub Check Run created by arno-check.yml reporting drift / lint / UUID-validity status against a commit SHA. ARNO reads these via the GitHub App webhook (check_run event) and via /debug/github/sync-check-runs backfill.

• Code: apps/api/src/github.ts (opens in a new tab), apps/api/src/webhooks.ts (opens in a new tab)

Pre-edit impact analysis

Synchronous check before a structural change to a component spec: surfaces every screen / instance that will be affected so the Maker can confirm.

• See: master spec §0.3 principle 9

Branch-aware view

Each Maker sees their own session-branch edits live; other Makers see main until a snapshot lands.

• See: master spec §0.8

Composition propagation

The killer feature: editing a component spec instantly updates every screen / instance using it across every project, because instances reference specs by UUID.

• See: master spec §0.1 ("Vision"), §0.3 principle 3 ("Identity ≠ name")

URL-import feature (master spec v1.3, §V unparked)

URL-import

The small-business onboarding flow: user provides a URL, ARNO extracts a working React component set (TSX + types + tokens + stories) covering all observed states, viewports, and themes.

• Spec: docs/url_import_spec.md
• ADRs: 0007 – 0018

Atom

A self-contained UI fragment extracted from a target page — e.g. a button, a card, a nav item. The building block the URL-import pipeline operates on before composing components.

• Code: packages/atom-poc/src/, packages/url-import-extractor/src/decompose.ts (opens in a new tab)
• Embedding: E5-small text embeddings, not visual — see ADR 0018

Staging area

V1 holding pen for imported components: ARNO writes to Modal Volume + Backblaze B2, not directly to the user's git repo. Promotes to PR in V2.

• Code: staged_component table
• See: ADR 0016

Shadow data

Anonymised extraction artifacts kept for the data flywheel (cost-decrease loop). Disclosed in ToS; opt-out via privacy settings (default ON).

• See: ADR 0017, PATCH /api/v1/me/settings

Completeness matrix

Empirical acceptance check for URL-import output: matrix of (state × viewport × theme) combinations actually exercised, not a single pointwise score.

• See: ADR 0009, ADR 0010

Reactive vision

VLM (Vision Language Model) is called only when the code-first pipeline fails or its result fails completeness — not predictively up-front.

• See: ADR 0011

Legal-clean distillation

URL-import LoRA teacher is Qwen (Apache 2.0), explicitly not Anthropic / OpenAI APIs, to keep redistribution rights clean.

• See: ADR 0014, ADR 0015

Operational

Runbook

Operational playbook for a paging alert. Lives in docs/runbooks/, one file per alert.

• Convention: master spec §II.9 — every PAGE alert must have a runbook

ADR

Architecture Decision Record. Captures why a decision was made, with context + alternatives + consequences. Immutable once Accepted (Deprecated / Superseded markers preserve history).

• Index: docs/adr/_index.md — auto-generated by pnpm docs:adr-index
• Template: docs/adr/README.md

docs-autogen

CI job that regenerates docs/api/** and docs/adr/_index.md from source on each push to main, then commits drift back.

• Code: .github/workflows/docs-autogen.yml (opens in a new tab)
• Scripts: scripts/gen-*.ts

INTERNALS.md

Per-package deep-dive documentation: how the module works inside, lifecycle, invariants, non-obvious behaviour. Distinct from _index.md (catalog) and README.md (intro).

• Enforcement: dangerfile.ts posts a warning when source under a package changes without the matching INTERNALS.md being touched.

Acronyms