Architecture

Reticle is a Cargo workspace of focused crates. The core geometry, indexing, and model crates are deliberately free of GPU, async, and UI code so they stay fast to test and clean to read; the heavier subsystems build on top of them.

Crate graph

graph TD
    geometry[reticle-geometry] --> index[reticle-index]
    geometry --> model[reticle-model]
    geometry --> io[reticle-io]
    proto[reticle-proto] --> io
    index --> render[reticle-render]
    geometry --> render
    model --> render
    index --> drc[reticle-drc]
    model --> drc
    index --> route[reticle-route]
    model --> route
    index --> extract[reticle-extract]
    model --> extract
    model --> sync[reticle-sync]
    sync --> server[reticle-server]
    model --> script[reticle-script]
    render --> app[reticle-app]
    model --> app
    sync --> app
    script --> app
    app --> web[web]
    io --> cli[reticle-cli]
    drc --> cli
    route --> cli

Responsibilities

The table above shows 15 crates. There are 30, and the 15 it omits are whole subsystems, not details. Added 2026-07-31, because this is the chapter a new reader opens first and reading it as an inventory hides the entire agent, MCP, plugin, generator, verification and interop surface:

This chapter shows the SHAPE, not the inventory. The complete per-crate table covering all 31 workspace members is docs/ARCHITECTURE.md section 3.2.2, machine checked by the dep-check leg of just ci; the per-file map is the generated docs/module-map.md. Re-derive the count with @(Get-ChildItem crates -Directory).Count.

What the crate ships and what the product reaches

These are different facts, and for two of reticle-io’s readers they differ. The KLayout .lyp (layer properties) and .lyt (technology) readers are real: parsed, bounded against malformed input, unit-tested, fuzzed, and public on the crate. Nothing the product ships calls either one. No Reticle build opens a .lyp or .lyt file, and there is no menu item, CLI subcommand, or drop target that accepts one. technology::layers_from_lyp, which merges a parsed .lyp onto a layer table, is likewise uncalled outside the crate’s own tests, and its own doc comment says the call site was never implemented.

Audited at 5c617540 (2026-07-29) over all 14 modules in crates/reticle-io/src/: 12 reachable from a crate outside reticle-io, 2 not. The audit re-runs as a test instead of sitting here as a dated sentence, and it fails in both directions, so giving .lyp an entry point breaks it and so does dropping a working format’s last call site:

cargo nextest run -p reticle-io --test parser_reachability

Design principles

• Exact integers. Coordinates are database units (DBU), never floating point; see the Geometry chapter and ADR 0002.
• Contract-first. The cross-crate types and traits are frozen before the subsystems that depend on them are written, so a change to a shared interface is a deliberate, reviewed event.
• Proven crates for hard problems. Polygon booleans (i_overlay), the R-tree (rstar), GDSII (gds21), rendering (wgpu), the CRDT (yrs), and routing primitives (pathfinding) are delegated to mature libraries; Reticle owns the domain logic that ties them together. The architecture decision records under docs/decisions/ explain each choice.
• Measure, never guess. Performance targets are backed by benchmarks run on real hardware; see the Performance methodology.

The local build gate

There is no hosted CI. A single just ci recipe runs formatting, Clippy with warnings denied, the test suite, a documentation build, a WebAssembly build, license and advisory checks, and a spell check. It must be green before every commit. See Contributing.