Duolith docs

Domain map

The framework is organised by domain-driven design: bounded contexts with their own words and owner paths, talking only through contracts. This page is the reference for that structure; the reasons are in decision records 0002 to 0004.

The allowed dependency directions are data in [tools/boundaries.yaml](../../tools/boundaries.yaml) and the ownership of paths is in [OWNERS.yaml](../../OWNERS.yaml). Both are checked in CI.


1. Domain-driven design: the bounded contexts

The framework is split into contexts. Each one has a single responsibility, its own words, one owner path in the repository and a public surface that other contexts use. Contexts talk only through the contracts in parallel-work.md.

ContextKindResponsible forLives in
LanguageCoreWhat a page file means: elements, attributes, directives, expressions, editionsspec/language, spec/glossary.yaml
SyntaxCoreTurning source text into a syntax tree, and back (formatting)crates/syntax, crates/fmt, editors/grammars
AnalysisCoreResolving names, checking rules, producing diagnostics and the Screen IRcrates/analyzer, crates/lint, spec/diagnostics
StylingCoreTokens, themes, utilities, prefixes and the style tablecrates/style
EmissionCoreTurning Screen IR into output for a targetcrates/emit-web, crates/emit-native, crates/script (shared script rewrites)
RuntimeCoreState, state that loads, actions, streams, bindings, boundaries, skeletons, motion, scheduling on the devicepackages/client, crates/runtime
NavigationSupportingRoutes, layouts, guards, transitions, morph, deep linkspackages/client/navigation, crates/analyzer/routes
KitSupportingBuilt-in parts, their pieces, variants, looks and overridespackages/kit, spec/kit
PlatformSupportingPlatform effects, permissions, app shells, lifecyclenative/ios, native/android, packages/effects, spec/effects
ModulesSupportingModule manifests, binding generation, the compatibility verdictpackages/modules, spec/schemas/module.schema.json
ToolingSupportingThe command-line tool, dev server, build report, doctor, explaincrates/cli
Editor intelligenceSupportingLanguage server, TypeScript plugin, compiler servicepackages/language-server, packages/ts-plugin, crates/wasm
Editor shellsGenericPackaging the server for each editoreditors/vscode, editors/jetbrains, editors/others
Agent surfaceSupportingSkills, llms.txt, the tool serverskills/, packages/mcp-server
DeliveryGenericEnvironments, signing, store uploads, release pipelinetools/release, crates/cli/ship

Core contexts are the product and get the most care and the strictest review. Supporting contexts are ours but conventional. Generic contexts follow each platform's standard way of doing things and should look boring.

The context map

                         ┌──────────────┐
                         │   Language   │  published language: every context conforms
                         └──────┬───────┘
                                │ language definition, glossary
             ┌──────────────────┼────────────────────┐
             ▼                  ▼                    ▼
        ┌────────┐        ┌──────────┐         ┌─────────┐
        │ Syntax │──tree─►│ Analysis │──IR───► │Emission │
        └────────┘        └────┬─────┘         └────┬────┘
                               │ diagnostics        │ generated code calls
                               ▼                    ▼
                    ┌────────────────────┐    ┌───────────┐  anti-corruption  ┌──────┐
                    │Editor intelligence │    │  Runtime  │◄─── layer ───────►│ Lynx │
                    └────────────────────┘    └─────┬─────┘  (engine adapter) └──────┘
                                                    │ ports
                         ┌──────────────┬───────────┼──────────────┐
                         ▼              ▼           ▼              ▼
                       Kit         Navigation    Platform    TanStack Query core
                                                 (effects)   (behind an adapter)

Three relationships are deliberate:

  • Language is a published language. Every other context reads the definition and the glossary; none of them invents its own terms for the same thing.
  • Lynx sits behind an anti-corruption layer. Only the engine adapter imports it. Lynx's words (element PAPI, main thread, background thread) never appear outside that adapter. This is what makes Tab 1's promise of swapping engines real.
  • Third-party cores sit behind ports. TanStack Query, UniFFI and each crash or analytics provider are reached through an interface we own, so replacing one changes one folder.

2. The ubiquitous language

One word per concept, used identically in the spec, code, docs, error messages, skills and conversation. The glossary is data in spec/glossary.yaml; the docs page and editor hover text are generated from it.

The glossary itself is data in [spec/glossary.yaml](../../spec/glossary.yaml). A summary of the core terms:

TermMeansNot to be called
pageA file in pages/ that becomes a route; markup, script block and stylescreen file, view, template
screenThe running instance of a page on a devicepage (at runtime)
componentA reusable file with markup, used by name inside a pagewidget
elementA built-in tag such as view, text, listnode, tag (in public APIs)
partA built-in kit component such as sheet or tabswidget, control
pieceA named, overridable section of a part, such as a sheet's handleslot (slot is a page concept)
lookThe starting visual style of the kit: default or platformskin, mode
variantA declared alternative of a component or part, such as primaryflavour, kind
tokenA named design value in the themevariable (except in the CSS output)
themeA complete set of token valuespalette
utilityA short class that applies tokens, such as p-4helper class
prefixA condition on a utility, such as pressed: or wide:modifier, variant
stateA reactive value, which may hold or load datastore, signal, resource (in public APIs)
actionAn asynchronous write with pending, error, retry and refreshmutation, command
streamState fed continuously by a live sourcesubscription, feed
bindingA link from state to a view property
boundaryA part of a screen that shows a skeleton until its state is readysuspense
skeletonThe placeholder drawn at a boundary while it loadsshimmer, placeholder
islandA unit of a screen that loads, updates and fails on its own
motionAutomatic or preset movement of an elementanimation (in public APIs)
morphAn element carried from one screen to anothershared element
transitionMovement between screens
interactionA module bundling a gesture, its state, motion and hapticgesture handler
moduleAnything installed with add: script, capability or componentextension, plugin, package
effectAn operating-system feature implemented per platform, such as hapticsnative module, capability
targetAn output: web, ios, androidplatform (platform is the OS)
rungA level of the execution ladder, 0 to 3tier, level
diagnosticAn error, warning or hint with a stable codeerror (generically)
Screen IRThe analysed, target-neutral description of a screenAST (it is not syntax)
editionA version of the language that a project opts into

Three rules keep it honest:

  1. A public name must be a glossary term or be made of glossary terms. A lint checks exported names in Rust and TypeScript against the glossary and flags the rest.
  2. Words from other systems stay inside their adapter. signal, query client, PAPI and mutation may appear only in the adapter that wraps them.
  3. The glossary changes like the language does, through a decision record. Who approves which changes is D37.

This draft also fixes contradictions in the source docs: "store", "resource" and "signal" become state; "extension" and "module" become module; "capability extension" becomes a module using effects.


3. Dependency rules

The arrows in the context map are the only allowed directions. CI enforces them; a pull request that adds a forbidden import fails.

RuleEnforced by
spec/ depends on nothingIt contains only data and schemas
Rust crates depend downward only: syntax ← analyzer ← emit-web, emit-native; style is used by analyzer and the emitters; cli and wasm sit on topcargo workspace layout plus tools/check-boundaries
No crate or package depends on cliBoundary check
Runtime packages (client, kit, effects) never import the compilerBoundary check
kit depends only on client's public API and tokensBoundary check
Only packages/engine imports Lynx; only packages/client/data-core imports TanStack QueryBoundary check
Editor shells depend only on the language server's protocol, never on compiler cratesBoundary check
No cycles, anywherecargo and a TypeScript cycle check
Generated code is produced only from spec/ and is never imported by spec/Generated-file check
Third-party dependencies need a one-line reason in the pull request and must have a compatible licencecargo-deny and a licence check

Each folder's README states, in one line, what it must not depend on. The check itself reads tools/boundaries.yaml, which is the authority when the two differ.