Part of the architecture notes indexed in AGENTS.md. Keep each topic in its bullet here; AGENTS.md only lists the topics.
Project (levels, materials, types: BTreeMap<ElementTypeId, ElementType>, elements, views) is the single source of truth. Every edit goes through Document::edit / edit_merged, which records a reversible Transaction (elements, views, types and project “settings” are tracked); continuous edits use edit_merged + break_merge. Uid is a persistent 128-bit id on project/types/elements (used as IFC GlobalId); Document::new, from_ron and add_element/add_type assign missing or duplicated ones. Files are versioned RON (persist.rs, FORMAT_VERSION): new fields must have serde defaults so older files load; bump the version for semantic changes. Old projects get missing ids and default annotation types on load.cc_core::component: a TypeData::Component { component, def } holds a ComponentDef (params + pieces); types sharing component share the definition and differ in parameter values (the editor applies changes to all of them). Piece fields are cc_core::expr expressions (bounded parser, errors as values), except fixed ComponentShape::Mesh pieces (imported geometry); a sketched piece’s ProfilePoints run straight, along an arc (radius) or along part of an ellipse (ellipse) to the next point, and cc_core::profile::from_curves/to_curves turn sketch curves into these vertices and back; ComponentDef::resolve returns prisms (mesh pieces also carry their faces) in the component frame plus per-piece errors, and cc_geom::component_parts places them in the world (plans draw mesh pieces with cc_geom::mesh_plan). .ccomp files (component_file.rs) are validated on load. A ComponentShape::Script piece is Lua whose geometry(p) returns other pieces (cc_core::component_script: ScriptEval, hotspots, limits; cc_script::object: declarations, builders, ScriptCache and shared(), sync); its declarations are copied into ComponentDef::params (from_script; text, boolean, choice and material kinds, booleans stored as 1/0) and hotspots, elements keep text_overrides and moved hotspots, ComponentDef::resolve_with takes them in a ResolveCtx, and cc_geom::resolve_instance/resolve_pieces run scripts through the shared cache (a failing script keeps each element’s last pieces); commands in cc_engine::commands::component_script. Doors and windows are components too (cc_core::openings): a ComponentKind::Door/Window definition with a HostOpening (width, height and default sill as expressions; own_symbol to draw its in-plan pieces instead of the category’s swing or sash lines, plan_only pieces being 2D symbols with no solid) makes types of the door or window category, whose ElementKind::Door/Window(Hosted) elements cut that opening in their wall; the pieces are resolved with WallThickness defined, in a frame centered on the opening (x along the wall, y towards the side the door opens to, z up from the sill), mirrored by the element’s flips (cc_geom::opening_parts, ModelGeometry::opening_fills). a window’s HostOpening::operation (cc_core::WindowOperation: fixed, side-hung left or right, double, top-hung, horizontal or vertical pivot, sliding; hinges for plan swings (dashed arcs, Drawing2D::dashed_arc), elevation_lines for the elevation symbol that doors share, ifc_panels/ifc_partitioning for IFC export, from_ifc_panels for import; openings::operable_window_def, OpeningNames::window_for) sets its plan symbol; ModelGeometry::opening_symbols holds the elevation symbols of doors and windows as unfilled outlines just off both wall faces, which projected::render orders with the faces so what stands in front hides them, and plans dash a window wholly above the cut; a door’s HostOpening::door_operation (cc_core::DoorOperation: one leaf hinged left or right, or a double door; hinges and elevation_lines as a window’s, ifc_operation/from_ifc the IFC operation type, ifc_panels the IfcDoorPanelProperties) draws a swing per leaf, and openings::operable_door_def/french_door_def (glazed leaves over a bottom_rail parameter, OpeningNames::door_for) are the built-in ones, made by door_type_create (cc_engine::commands::doors); ElementType::opening_size/default_sill/window_operation/door_operation read either kind; the template’s and IFC-imported door and window types are built-in definitions, and older files’ fixed TypeData::Door/Window types become them on load (format 12).Session (the Document plus cached geometry, drawings and sheets) and a catalog of commands (registry.rs). A command is a parameter struct (Deserialize + schemars::JsonSchema; its doc comment is the description, its fields’ doc comments the parameter docs) implementing Command { NAME, KIND, run }; register it in registry!. Names are snake_case (valid MCP/model tool names). Edits go through commands::edit, i.e. Document::try_edit + a repair check, so a command that would leave the model invalid is refused without an undo step. Levels, types, views and materials resolve by id or name (refs.rs); lengths in meters, angles in degrees, points [x, y]. *_get queries show the params that *_set commands merge (JSON merge patch over the model’s serde form). Errors are values (EngineError { code, message }); Session::execute guards panics. Creation defaults shared with the drawing tools live in defaults.rs; localization (i18n.rs, the t! macro) lives here too and cc_app::i18n re-exports it.cc_core::MeasurementSystem (metric, imperial) is not stored: a project is imperial when its length unit is (Units::system, Project::measurement_system); Units::imperial() (feet and inches to 1/16”, ft², ft³, SlopeUnit::RisePer12, format 28) is the imperial template’s and the Units dialog’s preset. project_new { template } and Project::from_template_system build either template from the same code, reading what differs from cc_core::template_spec (TemplateSpec: sizes and tpl-imp-* name keys, the stair and dimension style rules, library sizes rounded by units::round_imperial; concrete_walls, the reinforced concrete wall types: one Structure layer of the template’s concrete and structural: true, added last by add_template_concrete_walls and shown in the legend, not added to older projects on load), and cc_core::Defaults (Project::defaults) holds what commands and tools give things made outside the template per system (story and ceiling heights, the ramp, baseboard, tray, conductor, door, curtain and device sizes, pipe and device elevations, drain falls, rebar, terrain), so on-demand types get round imperial sizes and tpl-imp-* names. cc_core::scale writes and reads 1/4" = 1'-0" scales; SheetSize has the ANSI and ARCH sizes. Display goes through cc_views::format (thread-current units, set by Session::execute/sync and AppState::sync, with _with twins): length/meters/parse_length, size (small sizes: the metric form each place always had, MetricSize, or inches without feet, inch_size, parse_size reading a bare number as inches), area, volume, slope/parse_slope (6:12), scale, paper/paper_weight/parse_paper (sizes on paper, stored in mm), and quantity (Quantity: kg/lb, kg/m and lb/ft, kg/m² and lb/ft², kg/m³ and lb/ft³, MPa and ksi, l/s and gpm). Schedule headers come from ScheduleField::key_in(system) (col-imp-*, no unit), schedule Value::Size cells read in inches, check messages have *-imp-* twins; the app uses properties::length_drag, size_drag, slope_drag, paper_drag, field_label, rounds free points with tools::round_step (1/2” to 20’-0” in imperial) and AppState::follow_system moves tool sizes still at one system’s default to the other’s. Engine parameters and results, files, IFC and DXF stay SI; expressions keep their stored units; conductor cross-sections stay mm²; the metric output is pinned by tests/imperial_text.rs, which also scans an imperial project for metric units.cc_engine::graph: a Graph (.ccgraph, JSON, GRAPH_FORMAT; from_json bounds sizes, drops dangling, repeated and cycle-closing wires) of Nodes (NodeKind::Command — every catalog command, ports from its JSON schema through ports::type_of_schema, plus element for *_create; Builtin — builtin::catalog, pure, query or edit functions over JSON values; Lua — a pure function in the cc_script sandbox, no model access) joined by Wires. eval::Evaluator::run runs them in Graph::order (dependencies first, then lowest id), maps lists over ports (lace: a value deeper than the port’s rank runs once per item; shortest, longest, cross; MAX_CALLS), squashes the run into one undo step and caches outputs while the document revision is unchanged. Elements an edit command creates are bound in Project::graph_bindings (cc_core::graph_binding: graph uid, node, lacing path, index; tracked as settings, dropped with the element and by repair): on the next run the element made by the same call takes the new content and keeps its id, uid, mark, comments and phases (eval::bind), and bound elements whose call no longer ran successfully are deleted; failed, skipped and cached nodes keep theirs. Commands in cc_engine::commands::graph (graph_run, graph_check, graph_nodes, graph_elements, graph_release); ccad graph <file> key=value; examples/graphs/house.ccgraph is run by a test.mlua, vendored; no system Lua). sandbox.rs: a state with only table, string, math, utf8, coroutine and the base library minus load/dofile/loadfile/require/collectgarbage, an instruction budget per run (a global hook, so coroutines count) that pcall/xpcall/coroutine.resume re-raise, a memory limit and captured print. convert.rs: JSON ⇄ Lua (arrays carry the array metatable, whole floats become integers, depth and size bounded, cycles refused). api.rs: the ccad table (run, try, commands, describe, null, array, json); the session functions live only inside Lua::scope for a run, behind wrappers that stay, and an Access decides which command kinds a run may call. script.rs: run_script (ccad lua). store.rs: the community index (index.json, IndexPlugin::best picks the newest version for this build’s plugin API and version) and checked installs from downloaded bytes (SHA-256 against the index, the zip read in memory by cc_skp::zip with bounded sizes, no unsafe paths or links, the plugin loaded from a staging folder before it replaces the installed one), install_archive and uninstall; no networking. plugin.rs: plugin.toml manifests (id, api, main, permissions = ["files"]), require limited to the plugin folder, ccad.command { name, kind, params, run } collected while main.lua loads, and PluginHost, the cc_engine::Extension that runs <id>__<name> commands; grants are the host’s choice (Plugin::grant, only what the manifest asks). On the engine side extension.rs defines Extension; Session::execute takes it out while one of its commands runs (so plugin commands do not nest), squashes the command’s undo steps into one (Document::squash_since) and undoes them on failure, and records only top-level commands in macros; Session::commands/describe/kind_of list both; project_open replaces the document with Session::replace, which keeps the extension.ccad binary (no egui/wgpu): commands, schema, reference, run (JSON, @file, - or key=value arguments), script (JSON array or lines; stops at the first error), lua (a Lua script), graph (a .ccgraph, inputs as key=value), plugins, mcp (an in-house MCP server: JSON-RPC 2.0 over stdio, every command a tool with its schema; mcp.rs). Options -p (open .ccad or import .ifc), --save, --save-as, --plugins (repeatable; grants what manifests ask), --lang. What plugins print goes to stderr.