Loom
← Back to home

Loom — documentation index

This directory holds the reference and technical docs for Loom. The files are organised by audience, not by alphabetical order; pick the section that matches what you need.

Start here

Doc When to read
language-reference/ The complete language reference — every feature, one chapter at a time, each with the .ddd source and its real generated output in per-platform tabs. Start here when you want the exhaustive surface.
language.md You're writing or reading .ddd source. Declarations, types, expressions, statements, validation rules.
page-metamodel.md You're writing ui / page / component blocks.
customization-gradient.md You want the path from a fully-scaffolded UI to a fully hand-written one — override-by-name, unfold, and mixing rungs per page. The "no-code → no excuses" walkthrough.
architecture.md You want to know how module, deployable, api, storage, and ui compose into a runnable system.
tools.md You're using the ddd CLI (generate, verify, snapshot, patch, trace), .loomignore, watch mode, the docker workflow, or the OpenAPI parity check.
generators.md You want to know exactly what each backend (Hono, .NET, Phoenix LiveView, Java, Python) or frontend (React, Vue, Svelte, Angular, Feliz, Flutter) emits for a given DSL construct.
kubernetes.md You want to deploy the generated system to a cluster — the opt-in generate system --k8s Helm chart + raw manifests.
playground.md You want to know what the browser playground is — the typed editor, visual builders, live preview, and in-browser PGlite test runner at loom-harness.github.io/Loc/playground.

Per-feature references

These cover a single language feature each. Each one is self-contained.

Doc Feature
actions.md Page/component actions — named handlers, match await on a remote command, single- and multi-error-variant handling.
auth.md user block, auth: required, currentUser, requires, row-level permissions.
payloads.md payload / command / query / response / error records, the generic carriers paged / envelope, and discriminated unions (A or B, payload Foo = A | B, T option) with their tagged type wire. Also the numeric wire split — money is a fixed-scale string, decimal a JSON number.
inheritance.md abstract aggregate, extends, inheritanceUsing: sharedTable|ownTable — TPC (all backends) vs TPH (Hono only), and the polymorphic find all <Base> reader.
language-reference/06-behavior-and-statements.md Choosing a callable kind — decision table: operation vs create/destroy vs apply vs function vs domainService vs workflow vs commandHandler/queryHandler vs page action.
workflow.md workflow blocks, transactional vs non-transactional, isolation levels, event drain semantics.
channels.md channel / channelSource / the deployable channels: clause — cross-deployable eventing over redis/rabbitmq/kafka brokers, the CloudEvents envelope, outbox-relayed publishing, per-broker topology and auth.
resources.md storage / resource, source types, the objectStore / queue / api kinds, the config map, and workflow-level resource consumption (files.put, jobs.enqueue, rates.get).
extern.md extern operations and their per-backend handler registries.
criterion.md criterion — reusable named predicate specifications, shared across queries, validation, and permissions.
capabilities.md filter, stamp, implements — cross-aggregate behaviours like soft-delete, audit, tenant-ownership, and optimistic concurrency (versioned).
tenancy.md Multi-tenancy — tenancy by user.<claim> of <Registry>, the tenantOwned capability, crossTenant, and the explicit-stance rule.
domain-services.md domainService — stateless cross-aggregate pure calculators, the no-infra contract, and per-backend emission.
scaffold-macros.md The scaffold, crudish, audit, and softDelete macros — what they expand to.
stdlib.md The standard library — Layer-0 scalar intrinsics, collection operations, and the ambient prelude. Generated from the registries.
audit.md audited — the append-only command trail, and the derived entity-history read (GET /<agg>/{id}/history): the read-time field diff, what it excludes, and how the read gate, capability filters and mask unless compose onto it.
provenance.md provenanced field modifier, the ddd snapshot capture step, and the Hono runtime trace SDK.
observability.md The catalog envelope, per-backend log emission, the catalog extension surface.
traceability.md requirement / solution / testCase artefacts and the generated coverage report.
conformance.md The cross-generator OpenAPI parity harness — the nine dimensions, strict vs report-only mode (the structural wire contract).
conformance-semantics.md The runtime-value contract the spec-diff is blind to — named RS-rules (camelCase keys, enum casing, no leaked timestamps, association round-trip) seeded from the #1620–#1660 wire-parity sweep.
migrations.md MigrationsIR — the phase-⑨ schema-delta IR derived once and shared by every DB backend: how IR maps to tables/columns/join-tables, migrationsOwner, the shared Postgres SQL renderer, and where each backend applies migrations.
verify.md The ddd verify gate — joins a test-results JSON onto the requirements graph for per-requirement Definition-of-Done verdicts (VERIFIED / FAILING / UNVERIFIED / UNTESTED); CLI flags, results.json contract, and the emitted .loom/verification.*.
debugging.md You want to debug a generated app back to .ddd — the --sourcemap metadata (Source Map v3 / #line→PDB / JSR-45 SMAP), the emitted .vscode/launch.json for native editor debugging, the ddd trace / ddd breakpoints CLI, and the ddd-dap debug adapter.

Platforms, packs, stacks

Doc When to read
platforms.md You want to know which platform: values exist, how family@version pins resolve, and what the PlatformSurface contract is.
design-packs.md You're authoring a design pack (Mantine / shadcn / MUI / Chakra / Vuetify / shadcnVue / shadcnSvelte / flowbite / angularMaterial / primeng / spartanNg / coreComponents / daisyui). Covers manifest, stacks (v1/v3/vue1/sv1/ng1 framework baselines), required emits, template language, validation, and the recipe for adding a new pack version.

Internals

Doc When to read
technical.md The canonical pipeline reference — the ten phases from .ddd to disk. Read this before extending the language or adding a backend.
testing.md The test-tier placement guide — given a change, which tier proves it and where a new test belongs (fast vitest vs behavioral api/unit/ui vs per-backend build vs conformance vs playground e2e).
ci-gating.md The CI gating model — the per-PR / draft-gated / post-merge / nightly tiers, the pr-gate aggregate check, and the merge-queue runbook. Read this before assuming a green PR means a green main.
macro-api.md You're authoring a macro (stdlib or project-local). Covers defineMacro, parameter types, the factory surface, composability rules.
loom-artifacts.md The .loom/ output directory — wire-spec, mermaid + C4 diagrams, traceability files, verification, snapshots, and the opt-in sourcemap.json (ddd trace). What each artefact is and which CLI command produces it.
api-toolkit.md The transport-neutral src/api/ toolkit (validate / generate / outline / applyPatches + nav/refactor) and the src/diagnostics/contract.ts wire shapes — one browser-safe core behind the CLI, MCP, LSP, and playground.
mcp.md The MCP stdio server (ddd-mcp) + the transport-neutral loom_* agent-tool catalog — the three-layer tools/api/mcp stack and how to wire it into an MCP host.

Operational / legal

Doc When to read
license-faq.md "Is it OK to use Loom in production?", what counts as Competing Use, generator vs. generated-code licensing.

Subdirectories

See also