Part of the architecture notes indexed in AGENTS.md. Keep each topic in its bullet here; AGENTS.md only lists the topics.
generate(project, geom, view) returns a resolution-independent Drawing2D (lines with LineStyle, fills, anchored/rotated text in paper mm). Plans (plan.rs), projected views (projected.rs: elevations, sections, axonometric, painter’s algorithm ordered by pairwise depth comparison of overlapping faces; the silhouettes of a curved surface, the smooth edges to a facet turned away, are drawn only after the facets beside them, beside: those within a pen’s width on paper, SILHOUETTE_REACH_MM, which painted later would cover the line, unless a face not beside them hides them first), legends, schedules (schedule.rs: a ScheduleDef in the view picks fields, sort, filter and totals; headers and some cells are i18n keys; to_csv), sheets (sheet.rs: compose_sheet lays out border, title block and scaled viewports in paper mm; the app paints it and export.rs writes it as SVG, a hand-written PDF with standard Helvetica, or PNG through resvg with text drawn as Inter outlines by skrifa; view_on_paper lays out any view the same way for view_export; dxf.rs writes a drawing as DXF R12 for view_export/sheet_export: a view at full size in millimeters (DxfScale::model), a sheet in paper millimeters, layers named by the caller (the element’s category), dash patterns as line types, opaque fills as SOLID triangles, colors as the nearest ACI; linework::clean first makes elevations, sections and 3D views their visible linework, view_export hidden_lines: lines less what a later opaque fill covers, surface fills dropped, runs merged and chained into POLYLINEs by to_dxf_clean, the raw drawing when past its budgets) and annotations (annotate.rs: room/door/window tags, grids, dimensions; projected_grids draws in elevations and sections the grids running square to the view, as vertical lines with the bubble on top that belong to their grid, so the view’s graphics hide them by category or one by one, a section showing those between the ends of its line and between its cut and its depth). Dimensions store points in the view’s own drawing coordinates, so they work in any 2D view; in plans, elevations and sections each end may also reference a point of an element in its own frame (plus a height from its base or top in elevations/sections, through View::projection) or a level (cc_core::dim_refs), and every edit ends by moving referenced ends inside the same transaction (EditCtx::finish → sync_dimensions), so dimensions follow their elements and undo with them. A fill with alpha 0 is not hit-testable and only shows when its element is highlighted (room areas).cc_core::schedule::ScheduleDef (in ViewKind::Schedule): fields; filters: Vec<ScheduleFilter> (field, op: the view filters’ graphics::FilterOp, value; all must pass; MAX_FILTERS); sorting: Vec<SortLevel> (field, descending, header, footer, blank_line; MAX_SORT_LEVELS); collapse (one row for the elements alike in every sorting level); columns: Vec<ColumnFormat> (heading, align: ColumnAlign, hidden, total; only formats that say something are kept, format_of); appearance: ScheduleAppearance (grid_lines, outline, show_title, show_headers, three text sizes in mm); hide_totals; and bending. The older filter and sort_by/descending still load: all_filters/all_sorting read them first and normalize moves them into the lists (the dialog does on opening). check/repair bound everything (serde defaults, no format bump). ScheduleField::Count is 1 per element. cc_views::schedule::schedule_where filters (FilterOp::test on the value’s text and number; a value written its own way, a diameter Ø 12.5 or a slope, is a Value::Measured that filters and sorts by its number in SI units, diameters in meters and slopes as rise over run), sorts by the levels’ SortKeys, gathers rows when collapsed (Item: count, sums per field, the shared cell or schedule-varies), walks them emitting Row::headings, footers (Row::footer: count first, totals of the totaled columns) and blank lines per level (Group), leaves hidden columns out and fills Table::titles, align and appearance; Table::header_texts gives the headings, and draw_table draws the table as its appearance says (rows grow with the text; a column’s alignment applies to its heading too). cc_engine::commands::schedule: schedule_get, schedule_set (parts replace what they name; a filter’s value may be a JSON number, kept as text; columns merges by field, appearance is a patch); view_set checks a patched def. The app (schedule_ui.rs): props (the five Edit… rows of a schedule’s properties, Tab), open, and dialog with a page per tab (body the fields, filter_page, sorting_page, formatting_page, appearance_page), every change through engine_edit::view inside the dialog’s session; the table view shows the columns’ headings and group footers.cc_core::phase: Project::phases (time order), phase_filters and phase_graphics are tracked as settings; each element has phase_created (PhaseId(0) = unassigned, read as the last phase) and phase_demolished, each view a phase and phase_filter (templates control the filter only). Project::phase_state gives an element’s status in a view’s phase (existing, demolished, new, temporary, or absent); cc_views::graphics::PhaseView turns it into visibility and overrides inside the Resolver (phase overrides rank between view filters and the category). EditCtx::finish gives elements and views added by an edit the creation phase (Document::creation_phase, the active view’s) and applies Project::phase_fixes (hosted elements follow their hosts); repair resets bad references and files before version 11 get the template’s phases (ensure_phases). Rooms are bounded by the walls standing at the end of their creation phase (ModelGeometry::build_rooms), and a view whose phase leaves elements out uses ModelGeometry::build_phase (cached per phase in Session::view_geometry), so later doors do not open existing walls and walls join only within the phase. IFC export writes the status relative to the last phase as the common property sets’ Status plus the phase names (ConstructCAD_Phasing, ConstructCAD_Phases); import reads them back.cc_core::design_option: Project::option_sets (each an OptionSet with ordered DesignOptions and a primary) are tracked as settings; each element has design_option (None = main model), each view and template design_options (set → option; missing = automatic, TemplateIncludes::design_options off by default). Project::shown_options(view) gives one option per set: the view’s choice, else the option being edited (Project::active_option, #[serde(skip)] session state set through Document::set_active_option, which moves the revision without an undo step or dirtying the file), else the primary; option_shows tests an element. EditCtx::finish → sync_options puts model elements added without an option into the active one, applies Project::option_fixes (hosted elements follow their hosts, annotations and unknown options go to the main model) and drops stale view and template choices; repair_options does the same on load. ModelGeometry::build builds the main model plus the default options (Project::with_options), ModelGeometry::build_view the main model plus a view’s options in its phase, cached in Session::view_geometry by (phase, options); Session::element_geometry gives a non-shown option’s element its own (element queries). The Resolver hides elements of options a view does not show and schedules skip them, so options never join, open or bound rooms with each other. Deleting an option deletes its elements (the primary cannot be deleted); option_accept_primary merges the primary into the main model and deletes the rest. IFC export writes the main model and primary options only (DESIGN_OPTION_PSET, ConstructCAD_DesignOption), import recreates sets and options by name. Commands in cc_engine::commands::design_options; the app’s design_options_ui.rs holds the dialog, the Active Option menu and the property rows. Format 23.View::detail (cc_core::DetailLevel: Coarse, Medium by default, Fine; a template property, TemplateIncludes::detail): cc_views::plan_of cuts layered walls as one poché region at Coarse (DetailLevel::shows_layers), projected::render fills section cuts with the poché at Coarse, and component pieces carry DetailLevels (ComponentItem::detail → ComponentPart::detail → Solid::detail), filtered by plans, projected views and the 3D view (SceneMesh::build_at); commands: view_set/template_set detail, component_piece_set detail.View::visual_style (cc_core::VisualStyle: Wireframe, HiddenLine, Shaded, ConsistentColors, Textures; None reads as View::style, plans hidden line and other views shaded; a template property, TemplateIncludes::visual_style). cc_views::projected::render takes a Look (detail, style, pattern spacing): no fills and back faces’ edges in the wireframe, white faces in hidden line, the same white faces greyed by the light in shaded (ShadingSettings::grey: the view’s ambient plus the rest times the cosine to the light, as displayed, VisualStyle::shaded_grey at the defaults SHADED_AMBIENT/SHADED_DIFFUSE; no material colors), Solid::appearance and the Solid::surface hatches in textures (Solid::set_appearance); plans strip fills in the wireframe and lay plan::style_underlay (the faces below the cut, rendered looking down) under their linework in the colored styles. cc_render::SceneMesh::build_styled sets faces’ colors, SceneMesh::unlit, SceneMesh::grey (shaded: white faces times that grey in the shader, cast shadows ShadingSettings::shadow_grey, SHADED_SHADOW by default; build/build_plain, for thumbnails, keep the materials’ colors lit) and the vertices’ fg/bg surface patterns, which shader.wgsl draws procedurally along the vertices’ plane coordinates (meters on the face, see plane_axes; facet_shifts makes them run on across the smooth facets of a curved surface, for textures too) (naga validates it in a test). Material textures: MaterialAppearance::texture (cc_core::material::MaterialTexture: an Arc<RasterImage> bounded by MAX_TEXTURE_BYTES/MAX_TEXTURE_PIXELS, the repeat’s width/height in meters, offset, rotation_deg; map turns plane meters into repeats; repair drops a bad image); Solid::material names the solid’s material, cc_render::Tessellation keeps each vertex’s plane coordinates (plane_axes: plan X/Y on horizontal faces, level across and up on the others), cc_render::TextureSet decodes each material’s image once into a layer of a texture array (LAYER_SIZE, MAX_LAYERS, mipmaps made on the CPU; undecodable or extra images fall back to the color), SceneMesh::build_textured writes the vertices’ tex (repeats, layer + 1) in the textures style and Renderer3D::set_textures uploads the layers (bindings 1 and 2 of the shader). Painted faces: Element::paints (cc_core::paint::FacePaint: a point on the face, its outward normal and a material; moved by translate/transform, renamed with the material, dropped by repair when the material is gone); cc_geom::paint finds a paint’s face after each rebuild (the body face within NORMAL_TOLERANCE_DEG nearest the point, spread to the touching faces in its plane and the smooth facets joining it) and ModelGeometry::build ends by filling Solid::painted (face index → Look), which the tessellation splits into parts and projected::render reads per face; commands in cc_engine::commands::paint, the app’s Paint tool in paint_ui.rs (3D views only, cc_geom::paint::face_hit). Shading: View::shading (cc_core::ShadingSettings { ambient, shadow }: the light of faces turned away, 0.3 to 1, and how dark cast shadows are, 0 none to 1 black; serde default, not written at the defaults, repair clamps it and resets it on views that take no sun; grey, shadow_grey (a shaded shadow is 1 - shadow, never lighter than its face), darkening (the ground’s and the unlit styles’ shadows, none to black through their defaults)) is read by Look::shading (Look::of: projected faces, the plan underlay, shadow::veil/ground_veil, shadow::textures_light; veils go over a face’s fill and under its edges and surface pattern lines) and by Renderer3D::set_shading (Uniforms::shading: ambient, diffuse, shadow grey, the ground’s shadow opacity; style.z the unlit styles’ shadow), not by cc_raytracing; view_set/view_get shading (a merge patch, views::apply_shading); the app’s Ambient light and Shadow intensity rows (sun_ui::shading_rows, in view properties and the Sun Settings dialog).cc_core::graphics: each View has graphics (category visibility and overrides, applied FilterUses in order, element overrides, hidden elements) and an optional template; Project::filters (ViewFilter: categories plus rules on a ScheduleField or the level elevation) and Project::templates (ViewTemplate, with an include flag per property) are tracked as settings. EditCtx::finish → sync_views copies each template’s included properties into the views that follow it and drops references to deleted elements, filters and templates, so propagation is part of the same undo step. cc_views::graphics resolves an element’s graphics (Resolver: element override, then the first matching filter, then the category, attribute by attribute) and applies them to the generated Drawing2D (lines carry a Pen, fills know whether they are cut, material hatch lines are LineStyle::Hatch, texts carry their element); cc_render::SceneMesh::build takes a per-element SolidStyle. Temporary hide/isolate is session state (Session::set_temporary), not model state: Session::drawing applies it, sheets and exports use printed_drawing.ViewKind::Drafting {} (category ViewCategory::Drafting, view_create kind: "drafting", 1:10 by default) is a 2D view independent of the model: cc_views::generate starts it from an empty drawing and adds only the elements it owns (Element::owner_view: text notes, dimensions, imported CAD drawings and pictures, hosts_cad), then applies its graphics. It has its own scale and detail level and visibility/graphics (ViewKind::has_graphics) but no template, phase or visual style; dimensions go in it (View::takes_dimensions) without references to the model. It is placed on sheets and exported like any view; remove_view deletes what it owns. The app: View → Drafting View (UiCommand::DraftingView) and the browser’s Drafting Views group. View-owned 2D elements (detail lines, regions, detail components) belong in it the same way.cc_core::callout: a floor plan, ceiling plan, section or elevation (ViewKind::croppable) may have View::crop, a CropBox (min/max in its drawing coordinates, MIN_CROP, MAX_CROP); cc_views::generate ends with callout::crop, which clips lines (Liang-Barsky) and fills (Sutherland-Hodgman) of everything the view does not own and drops texts and pictures outside it (view-owned elements stay whole; d.underlay, tags and marks follow). A callout lives on the view it stands for, View::callout (Callout { parent, rect }): a detail view keeps the parent’s kind and its crop is the callout’s rectangle (rect is None), a drafting view a callout points to keeps rect; View::callout_rect/set_callout_rect read and move either, so the mark and the crop are one value and deleting the view removes the mark. EditCtx::finish -> sync_callouts (Project::detail_kind, details of details up to MAX_CHAIN) makes a section’s or elevation’s detail take its parent’s kind and a plan’s detail its level; remove_view drops callouts of a deleted parent (the details stay, cropped); repair_callouts drops invalid crops and callouts whose parent is missing, itself, not croppable or of another kind, or with no rectangle. cc_views::callout::marks draws a view’s callouts (Project::callouts_in): a rounded rectangle and a 12 mm tag on a leader with the number on its sheet over the sheet number (plan::section_labels), listed in Drawing2D::callouts (CalloutHandle, callout_at); plans skip detail views in section and elevation marks (View::is_detail). cc_engine::commands::callout: callout_create (parent, rect, scale default detail_scale, name, drafting), callout_remove, callouts_list; view_set crop (nullable; a drafting callout’s rectangle), view_get crop and callout; view_duplicate drops the callout. No format bump (serde defaults). The app (callout_ui.rs): View -> Callout (UiCommand::Callout, Tool::Callout, options AppState::callout: scale or a drafting view), marks picked by the Select tool before section marks (AppState::section_selection holds the selected mark’s view, so Delete deletes it and the palette shows its view), Drag::Callout moves the mark or a corner through engine_edit::view, a double-click opens the view, and view_rows adds the callout and crop rows to view properties.cc_core::browser: Project::browser (BrowserOrganization: named BrowserSchemes with their group_by criteria, outermost first, and the active one; tracked as settings, EditCtx::browser_mut; serde default, no format bump; repair fixes ids, names, criteria and a missing scheme in use) says how the project browser groups the views. GroupBy is ViewType, Level, Discipline (Discipline::of: architecture, structure or a plan’s MepDiscipline) or Phase; with no scheme in use the grouping is DEFAULT_GROUPING (view type alone). browser::tree builds the Nodes (groups with a GroupKey, views): at each depth the views that have a value go into a group per value in its order (types as ViewCategory::ALL, levels and phases as the project lists them), the others go on to the next criterion beside those groups, and every view type shows at the root, empty or not; views are sorted by their level’s elevation, then by browser::label. cc_engine::commands::browser holds browser_schemes_list, browser_scheme_create, _set, _delete, _use and browser_tree (refs::browser_scheme). The app’s browser.rs draws Project::browser_tree recursively (nodes, tree_row with a guide line per depth; the open state is kept per path of group keys, and a view type at the root keeps its “+” button), and browser_org_dialog.rs is the dialog (View → Browser Organization, UiCommand::BrowserOrganization, and the groups’ context menu): the marked scheme is the one in use.