Duolith docs

Principles

How code in this repository is organised and written. The rules here are summarised in AGENTS.md and given in full, with examples, in CONTRIBUTING.md. The domain structure is in domain.md.


1. Simplification principles

  1. One way to do each thing. If there are two ways, one of them is a bug in the design.
  2. Delete before adding. A new concept must replace one or fit inside one of the seven. The Language context keeps the count.
  3. Data over code. Behaviour that can be a table (styles, bindings, motion, routes, diagnostics, kit variants) is a table, generated from spec/, executed by a small engine.
  4. Conventions over configuration. A setting exists only when a real app needs to differ from the default.
  5. Seams only where we expect change. There are exactly four designed seams: the engine adapter, the data core adapter, the platform effect interface, and provider adapters. Everywhere else, write the concrete thing.
  6. Small public surfaces. Each context exports as little as it can; everything else is private by default (pub(crate) in Rust, no export in TypeScript).
  7. Make wrong states unrepresentable. Prefer types that cannot hold an invalid value to checks that catch one.
  8. Boring technology outside the core. Novelty is spent on the language and the compiler, not on build scripts.
  9. Later means written down. Anything deferred goes on the post-v1 list in docs/plan/, so nobody adds half of it now "while they are there".

2. Code as prose

Code is read far more often than written, and here it is often read by an agent starting cold. These rules make a file readable top to bottom.

Naming

  • Names come from the glossary. A function says what it does in domain words: resolve_binding, emit_skeleton, refreshAfterWrite.
  • No abbreviations except those in the glossary (IR) and universal ones (id, url).
  • Booleans read as questions: is_static, hasPendingWrites.
  • Functions are verbs, types are nouns, modules are the concept they hold.

Shape

  • Top-down. A file opens with its public entry point, written as a short sequence of steps, each step a well-named call. The helpers follow below in the order they are first used. A reader stops reading when they have enough detail.
  • Small functions that do one thing. About 30 lines is the guideline. Whether a lint enforces a limit is D38.
  • One concept per file, named after the concept.
  • Early returns over nested conditions.
  • No flag arguments that switch behaviour; write two functions.
  • No clever code. If a line needs a comment to explain what it does, rewrite the line.

Comments and docs

  • Every module begins with a doc comment: what it owns, what it must not depend on, and the glossary terms it uses.
  • Comments explain why, never what.
  • Public items have doc comments with an example that compiles, which CI runs.

Errors

  • Rust returns Result; the compiler never panics on user input. Every user-facing failure is a diagnostic with a code.
  • TypeScript runtime failures carry the diagnostic code and the page file and line.

Tests read as specifications

  • Test names are sentences: a_list_bound_to_paged_state_requests_the_next_page_near_the_end.
  • Arrange, act, assert, with blank lines between.
  • Conformance fixtures are named after the rule they demonstrate.

A short example of the shape, in Rust:

//! Builds the skeleton template for a boundary.
//! Owns: skeleton sizing. Must not depend on: emitters, runtime.
//! Terms: boundary, skeleton, element, token.

pub fn build_skeleton(boundary: &Boundary, styles: &StyleTable) -> Skeleton {
    let layout = measure_layout(boundary, styles);
    let shapes = layout.elements().map(shape_for_element).collect();
    Skeleton::new(shapes).repeated_to_fill(boundary.available_space())
}

fn measure_layout(boundary: &Boundary, styles: &StyleTable) -> Layout { /* ... */ }

fn shape_for_element(element: &MeasuredElement) -> Shape {
    match element.kind() {
        ElementKind::Text  => Shape::text_bars(element.font(), element.expected_lines()),
        ElementKind::Image => Shape::block(element.aspect_ratio()),
        _                  => Shape::empty(),
    }
}

The entry function reads as one sentence: measure the layout, turn each element into a shape, repeat to fill the space.


3. Where each rule lives

RuleIn the repository
Context list, map and responsibilitiesdocs/explanation/domain.md; one line in each folder's README
Glossaryspec/glossary.yaml, generated to docs/reference/glossary.md and editor hovers
Simplification principlesdocs/explanation/principles.md; summarised in AGENTS.md
Code-as-prose styleCONTRIBUTING.md style section; summarised in AGENTS.md; enforced partly by lint
Dependency rulesdocs/explanation/domain.md, enforced by tools/check-boundaries
Parallel-work rulesskills/contrib/parallel-work/SKILL.md, docs/plan/

4. What goes into AGENTS.md and CONTRIBUTING.md

**Root AGENTS.md gains a section "How code is organised here":**

  • The context table, one line each, with its folder.
  • "Use glossary words. Words from Lynx, TanStack or a provider stay in their adapter."
  • "Write top-down: entry point first, helpers below, each function one step."
  • "Only depend in the directions in docs/explanation/domain.md. CI will reject anything else."
  • "Work only inside your brief's owner paths."

**Each nested AGENTS.md** names its context, its glossary terms, its public surface and its forbidden dependencies.

**CONTRIBUTING.md** carries the full style guide from section 2 with examples in Rust and TypeScript, the dependency rules, and how to propose a glossary or contract change.


5. First decision records

Written in WP0, numbered in this order:

  1. 0001 Record architecture decisions
  2. 0002 Bounded contexts and the context map
  3. 0003 The glossary is part of the specification
  4. 0004 Dependency rules and how they are enforced
  5. 0005 Code-as-prose style
  6. 0006 Contract-first parallel work with sub-agents
  7. 0007 Lynx behind an engine adapter
  8. 0008 Rust compiler using oxc and lightningcss
  9. 0009 Licence (from D3)
  10. 0010 Name and file extension (from D1, D2)

Records for D16 to D25 follow with Specification v0.