Duolith docs

Decision records

One record per significant choice, numbered, never rewritten after acceptance. Template: 0000-template.md. "Accepted (provisional)" means adopted on a recommendation while Mik's answer is pending (see 0001).

#DecisionStatus
0001Record architecture decisionsAccepted
0002Organise the repository into bounded contextsProvisional
0003The glossary is part of the specificationProvisional
0004Dependency rules, enforced in CIAccepted
0005Code as proseProvisional
0006Contract-first parallel work with sub-agentsProvisional
0007Lynx behind an engine adapterSubject to spike
0008Rust compiler using oxc and lightningcssProvisional
0009Licence: MIT OR Apache-2.0Provisional
0010Codename "strata" until the public name is chosenSuperseded by 0161
0011Provisional answers to the planning decisions listProvisional
0012Build a thin walking skeleton for web before Specification v0Provisional
0013Control flow is written as markup: show, otherwise and keyed listsProposed
0014Derived values, two-way binding and the new eventsProposed
0015Components are files in components/, imported explicitly, with props declared in the scriptProposed
0016Grow the utility vocabulary from data, with fixed scales beside theme tokensProposed
0017Add hover, and md and lg window-size prefixes at 768px and 1024pxProposed
0018A project theme is a schema-checked theme.yaml that also chooses the colour schemeProposed
0019Write the data core ourselves, behind the adapter meant for TanStack QueryAccepted
0020The data layer is objects with reactive properties, named as in the briefAccepted
0021Environment values reach a page as a global set by the buildProposed
0022One formatting style for page files; the script block is kept as writtenAccepted (provisional)
0023The TextMate grammar is generated from the language definitionAccepted (provisional)
0025The language server runs on Volar, with the compiler built to WebAssemblyProposed
0026One TypeScript "script view" per page for editor intelligenceProposed
0027The language definition says how each attribute is written and what each handler receivesProposed
0031Routes come from file names, layouts wrap folders, and an app is a stack of screensAccepted
0032Transitions are kinds of navigation, and each target plays its own movementProposed
0033A screen guards itself with guard(...), and screens share state by nameAccepted
0028Kit parts are .duo components built into the compiler and imported from @duolith/kitProposed
0029Language additions the kit needs: conditional classes, bindable props, pieces, roles, disabled and four elementsProposed
0030A small built-in icon set, placed with iconProposed
0034One overlay element, with a kind, shown in one overlay layerProposed
0035Overlay parts open with bind:open or a trigger piece; menus take their items as dataProposed
0036toast() is a runtime function from @duolith/client, shown by the kit's Toast regionProposed
0037Navigation keys, Tab stops, spinbutton values and new roles for pickers and tabsProposed
0038Images load through a runtime cache: one fetch and one decode per addressProposed
0039Chips are toggle buttons; zoom is an image zoomable mode, shown by an ImageViewer partProposed
0040The kit's navigation parts sit on the router: tabs match the route, a tab bar can become a rail, and three new rolesProposed
0041canGoBack() and backTitle() say whether a screen was pushed, and from whatAccepted
0042A project's public/ folder is copied to the site as it isProposed
0045Native output is ReactLynx, written against an engine adapter; styles become looksProposed
0046The native output is verified without a device (snapshots, tsc, a Lynx bundle, Lynx for Web); a checklist covers the restProposed
0047On native, the engine plays screen transitions and places anchored overlays, and the build makes up for CSS that Lynx dropsProposed
0048On native, effects cross one JSON bridge, and an effect not built for native fails the buildProposed
0049A native build honours each feature or stops with an error, and says how a style opts out of a phoneProposed
0065duolith test builds the project and runs *.test.ts files in Chromium with @duolith/testingAccepted
0066The compiler service gives a page outline; the language server's features come in six checked groupsAccepted
0067Editions, and duolith upgrade moves a project to one with migrationsAccepted
0068The reference docs are generated from spec/, and the CLI's commands are spec tooProposed
0069duolith dev emits source maps, and our own debug adapter puts breakpoints on page linesProposed
0080Lint rules are coded warnings, set per project in duolith.yaml, run by duolith lintAccepted
0050Effects are imported by name from @duolith/effects; each contract has an app-facing half and a platform halfAccepted
0051Permission declarations are written at build time from the effects an app importsAccepted
0052On the web, secure storage encrypts with a non-extractable key, and sign-in redirects with PKCEProposed
0053The production adapters run on native with the shell as their hostAccepted
0054Native motion, morphs and skeletons live in the engine adapter, not crates/runtimeAccepted
0055Elements move by themselves when shows and lists change, and motion= names a presetAccepted
0056Morphs and the back gesture ride on the screen transitionAccepted
0057A load directive makes a placed component an islandAccepted
0058<boundary> catches failures, and shows its <fallback> with a retryAccepted
0059Skeletons are derived from the layout, or remembered from the last real oneAccepted
0060The agent reference (llms.txt and llms/) is generated from spec/ and docs/, and split by topicAccepted
0061The tool server answers through the Duolith command; create is a node command for nowAccepted
0062A skill's evaluation is a task, a check and a reference solution, run both waysAccepted
0070Production adapters are one package of ports, imported like the runtime, with two runtime hooksAccepted
0071Consent gates analytics and crash reporting, by category, and honours Global Privacy ControlProposed
0072Translation is t() with ICU messages in locales/<locale>.json, checked at build timeAccepted
0073duolith scan gives each npm dependency a verdict for the targetsProposed
0074Crash reports carry the screen, breadcrumbs and frames mapped to .duo filesProposed
0075Rung 0: a file whose expressions are all constants is built as tablesProposed
0076Rung 1 ships source until the spike's timing opens the bytecode gate; rung 2 stays closedAccepted
0077The web keeps keyed list moves in TypeScript; the Rust version is for nativeProposed
0078Rust modules live in modules/<name>/, are imported by folder, and are built with wasm-bindgen and UniFFIAccepted
0079duolith build --report writes build-report.json and prints a summaryAccepted
0090The docs site is generated from the repository by a small script, not built as a Duolith appProposed
0091Release names are placeholders until Mik chooses them, and the pipeline is a dry runAccepted
0092One version for everything, worked out from the change notesProposed
0095Every typed position in markup is checked by TypeScript, through the script viewAccepted
0096duolith check runs the real TypeScript checker, and every build and dev server runs itProposed
0097Pages are checked with the strictest practical TypeScript optionsAccepted
0098A <match> element for unions, and a resource's states as a unionAccepted
0099Paths written as text are checked when the app is builtProposed
0085Editor shells beyond VS Code: LSP4IJ and the TextMate bundle in JetBrains, the HTML tree-sitter grammar elsewhereProposed
0100Page files are highlighted everywhere from the TextMate and tree-sitter grammars; every registry and upstream submission waits for MikAccepted
0101The device effects, and how each says a platform cannotAccepted
0102The device effects ask for no more than they use, and the build says what a phone would refuseAccepted
0103Platform looks, and per-part overrides in theme.yamlAccepted
0104A typed API client from an OpenAPI descriptionAccepted
0105Environment files, and a typed environment()Accepted
0106autocomplete on fields, mapped to each platform's autofillAccepted
0107An optimized web build: minified, with hashed names and an import mapAccepted
0108Sixteen more kit parts, and the expanded and sorted attributesAccepted
0109The typed client types every part of an operation, or refuses itAccepted
0121on:swipe, and the gesture parts built on itAccepted
0110Every effect is built for native: sign-in, push, purchases and camera on iOS and AndroidAccepted
0140The app manifest is a group of duolith.yaml, and duolith ship builds store releases from itAccepted
0141Links reach the router through the shell, other sites open in the system, and a dev server reloads the app on a phoneAccepted
0145An installed Duolith carries its Node companions, and the templates carry testsAccepted
0146duolith add decides what to add by what the name is, and keeps a package only when it can shipAccepted
0147Tests mock any effect named in effects.yaml, and compare screens with a toleranceAccepted
0148duolith locales extract adds a key for each untranslated text, named after its pageAccepted
0149Editors run tests, previews and other project jobs through the Duolith commandAccepted
0150A strict Content-Security-Policy on every web build, set in duolith.yamlAccepted
0151The effect bridge has one typed contract, generated for Kotlin and Swift and checked in debug buildsAccepted
0152Behaviours: script written once and used from any file's scriptAccepted
0160Packs: Duolith's and an app's rules and skills, one topic each, proved by the compiler and served to agentsAccepted
0161The public name is Duolith, and pages are .duo filesAccepted
0162A web build writes each page's HTML, and ships script only where a page runsAccepted
0163A server companion renders on request only what the build cannot write (the server after version 1, its serverless stages in it)Accepted
0164Domain files generate an API's models, validators, client and server wiring (after version 1)Accepted
0165Every server request runs one pipeline, compiled per operation, with templates an app can replace (after version 1)Accepted
0166Transports, live updates and resilience are options on the domain, with measured defaults (after version 1)Accepted
0167A workflow is declared on the domain, checkpointed in the store, and always reaches an end (after version 1)Accepted
0168The build sizes the system, prices it and generates its infrastructure (after version 1)Accepted
0169Any domain, operation or function can be moved to its own server by naming it, and the move is tracked until the old place is retired (after version 1)Accepted
0170The server work is built in full, and proven on one example: a social app and its website (after version 1)Accepted
0171The server is a small core, and every target, store, engine, broker and library is a module, added by the CLI and checked on every upgrade (after version 1)Accepted
0172An agent works in one scope, named by something the build already knows (a domain, an operation, a page, a tier, a server, a module), and a change outside it is refusedProposed
0173Database code, starter domains and an admin are each added by choice, and the framework never requires an ORM (after version 1)Proposed

In this section