# astepaniuk/cad-research architecture

> Architecture diagram of the GitHub repository astepaniuk/cad-research, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astepaniuk/cad-research
- Repository: https://github.com/astepaniuk/cad-research

## Overview

1. **Overall shape**
   - This is a C++/CMake desktop CAD prototype centered on **2D floor-plan editing**.
   - The code is split into three main product layers: **core infrastructure** (`corecad`), **domain logic** (`domain/plan`), and **GUI/editor** (`gui`).
   - Tests are organized by the same boundaries, which makes the intended architecture fairly explicit.

2. **Build and dependency boundaries**
   - The project is built with **CMake** and uses **vcpkg** for package management.
   - Two bundled third-party dependencies matter architecturally:
     - **ImGui** for the immediate-mode UI.
     - **freecad-planegcs** for geometric/constraint solving in the sketcher-like parts of the model.
   - The repository also includes a standalone GitHub Actions workflow for multi-platform CMake builds.

3. **CoreCAD: shared modeling infrastructure**
   - `src/corecad` is the generic, reusable foundation beneath the plan domain.
   - It contains infrastructure for:
     - **model objects and properties**
     - **registries / stable indexing**
     - **trackable registries**
     - **history/undo-redo transactions**
     - **generic constraints and calculators**
   - This layer looks intentionally domain-agnostic: it provides the mechanics for state management, referencing, and calculations without knowing about walls or floors.

4. **Domain model: floor-plan concepts**
   - `src/domain/plan/model` defines the actual business objects:
     - `floor`
     - `wall`
     - typed **parameters** such as `distance`, `point_locator`, and `wall_border_point_locator`
   - The domain model is split into subfolders for **shape** and **parameter**, which suggests the design separates geometric entities from their editable/derived inputs.

5. **Domain generation and resolution**
   - `src/domain/plan/generator/default_floor_generator` creates initial floor content.
   - `src/domain/plan/resolver/point_resolver` and the parameter locators suggest a two-step approach:
     - resolve abstract/editable parameters into concrete geometric points
     - then use those points to drive shape updates
   - This is the bridge between user intent and actual geometry.

6. **Domain calculation**
   - `src/domain/plan/calculator/wall_calculator` is the central computation unit for wall geometry.
   - The tests show it calculates **wall borders** for:
     - a single wall
     - added walls
     - two walls
     - multiple joined walls
   - That implies the calculation layer is responsible for updating wall extents and intersections when topology changes, not just storing coordinates.

7. **GUI application boundary**
   - `src/gui/main.cpp` is the application entry point.
   - `main_window` is the top-level UI shell, with a `workspace` and `main_menu` around the active editor/document area.
   - The GUI is organized around a central document/view/editor structure rather than a generic widget tree.

8. **Document and view layer**
   - `src/gui/doc/document.h` appears to hold the editable document state for the UI.
   - `wall_snaps` sits in the document layer, hinting that snapping aids are part of document state or derived document services.
   - `src/gui/view` contains rendering-oriented views:
     - `floor_view`
     - `walls_view`
     - `constraints_view`
     - `parameters_view`
   - `coord_translator` indicates a clear separation between screen coordinates and model coordinates.

9. **Editor interaction pipeline**
   - `src/gui/editor` is the interaction engine for manipulating the model.
   - The structure is stateful:
     - `operation` classes represent active tools or modes such as add-wall, idle, and move-wall-handle.
     - `handler` classes encapsulate specialized behaviors like wall joins and T-joins.
     - `mouse` centralizes pointer state.
   - This suggests a tool-driven editor architecture where input events are interpreted by the active operation, which then mutates the document/model.

10. **Snapping and editing assistance**
   - `src/gui/editor/snap` contains snap construction and processing:
     - `vh_snap_builder`
     - `snap_processor`
     - `i_snap_builder`
   - These components likely compute candidate alignments or target points before the editor commits a move or placement.
   - Snapping sits between raw mouse input and model mutation, acting as an editor-side geometric assistance layer.

11. **Calculation pipeline in the GUI**
   - `src/gui/editor/calc_pipeline` suggests the GUI has its own orchestration layer around calculations, probably to sequence resolver/calculator passes while editing.
   - This is important architecturally because it means geometry updates are not direct UI writes; they likely flow through a staged pipeline that keeps the view/editor responsive and model-consistent.

12. **Data flow through the system**
   - The main flow is:
     - user input in the GUI
     - active editor operation/handler interprets the input
     - snap processing and point resolution refine the edit intent
     - domain model changes are applied
     - calculators recompute wall/floor geometry and constraints
     - views render the updated document
   - Undo/redo and transaction history in `corecad/model/history` wrap this flow so edits are reversible.

13. **Testing boundaries mirror the architecture**
   - `corecad_tests` focus on **history/transaction behavior**.
   - `domain_tests` focus on **wall calculation correctness**.
   - `common_test_util` provides assertion helpers shared across test groups.
   - This separation reinforces that the repo’s primary design concerns are model consistency and geometric recalculation, not just UI behavior.

14. **Likely diagram boundaries**
   - A clean architecture diagram should show:
     - **GUI/editor** at the top
     - **Domain plan model + calculators** in the middle
     - **CoreCAD infrastructure + history/constraints** underneath as reusable services
     - **Third-party geometry/solver libraries** as external dependencies feeding the calculation layer
   - The most important cross-boundary interactions are editor-to-domain updates, domain-to-calculator recomputation, and history wrapping of state changes.

Main entry points: [`src/domain/plan/model/floor.h`](https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/model/floor.h) (Floor), [`src/domain/plan/calculator/wall_calculator.h`](https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/calculator/wall_calculator.h) (Wall calculator), [`src/gui/main_window/main_window.h`](https://github.com/astepaniuk/cad-research/blob/main/src/gui/main_window/main_window.h) (Main window), [`src/gui/editor/floor_editor.h`](https://github.com/astepaniuk/cad-research/blob/main/src/gui/editor/floor_editor.h) (Editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_build["Build & deps"]
  node_n_cmake["CMake build<br/>build system<br/>[CMakeLists.txt]"]
  node_n_vcpkg["vcpkg<br/>package manager<br/>[vcpkg.json]"]
  node_n_imgui["ImGui<br/>ui library<br/>[CMakeLists.txt]"]
  node_n_freecad["PlaneGCS<br/>solver library<br/>[CMakeLists.txt]"]
end

subgraph group_grp_core["CoreCAD"]
  node_n_core_model["Model base<br/>core model<br/>[model_base.h]"]
  node_n_core_history["History<br/>undo/redo<br/>[model_history.h]"]
  node_n_core_registry["Registries<br/>indexing<br/>[registry.h]"]
  node_n_core_constraints["Constraints<br/>[constraint.h]"]
  node_n_core_calc["Constraint calc<br/>calculation"]
end

subgraph group_grp_domain["Plan domain"]
  node_n_floor["Floor<br/>domain entity<br/>[floor.h]"]
  node_n_wall["Wall<br/>domain shape<br/>[wall.h]"]
  node_n_params["Parameters<br/>editable inputs<br/>[parameter.h]"]
  node_n_generator["Default generator<br/>domain generator"]
  node_n_resolver["Point resolver<br/>resolution<br/>[point_resolver.h]"]
  node_n_wall_calc["Wall calculator<br/>geometry calc<br/>[wall_calculator.h]"]
end

subgraph group_grp_gui["GUI/editor"]
  node_n_main["App entry<br/>desktop app<br/>[main.cpp]"]
  node_n_window["Main window<br/>shell<br/>[main_window.h]"]
  node_n_doc["Document<br/>ui state<br/>[document.h]"]
  node_n_views["Views<br/>render layer<br/>[floor_view.h]"]
  node_n_editor["Editor<br/>interaction engine<br/>[floor_editor.h]"]
  node_n_snap["Snapping<br/>editor assist<br/>[snap_processor.h]"]
  node_n_pipeline["Calc pipeline<br/>orchestration<br/>[calc_tools.h]"]
end

node_n_cmake -->|"uses"| node_n_vcpkg
node_n_cmake -->|"builds with"| node_n_imgui
node_n_cmake -->|"builds with"| node_n_freecad
node_n_main -->|"starts"| node_n_window
node_n_window -->|"hosts"| node_n_doc
node_n_window -->|"renders"| node_n_views
node_n_window -->|"drives"| node_n_editor
node_n_doc -->|"contains"| node_n_snap
node_n_editor -->|"uses"| node_n_snap
node_n_editor -->|"triggers"| node_n_pipeline
node_n_editor -->|"mutates"| node_n_floor
node_n_snap -->|"refines to"| node_n_resolver
node_n_pipeline -->|"runs"| node_n_resolver
node_n_pipeline -->|"runs"| node_n_wall_calc
node_n_floor -->|"contains"| node_n_wall
node_n_floor -->|"uses"| node_n_params
node_n_generator -->|"creates"| node_n_floor
node_n_resolver -->|"resolves"| node_n_params
node_n_wall_calc -->|"updates"| node_n_wall
node_n_wall_calc -->|"relies on"| node_n_core_calc
node_n_wall_calc -->|"solves with"| node_n_freecad
node_n_floor -->|"built on"| node_n_core_model
node_n_floor -->|"versioned by"| node_n_core_history
node_n_floor -->|"indexed by"| node_n_core_registry
node_n_params -->|"describes"| node_n_core_constraints
node_n_views -->|"reads"| node_n_core_model
node_n_views -->|"observes"| node_n_doc

click node_n_cmake "https://github.com/astepaniuk/cad-research/blob/main/CMakeLists.txt"
click node_n_vcpkg "https://github.com/astepaniuk/cad-research/blob/main/vcpkg.json"
click node_n_imgui "https://github.com/astepaniuk/cad-research/blob/main/3rd-party/imgui/CMakeLists.txt"
click node_n_freecad "https://github.com/astepaniuk/cad-research/blob/main/3rd-party/freecad-planegcs/CMakeLists.txt"
click node_n_core_model "https://github.com/astepaniuk/cad-research/blob/main/src/corecad/model/model_base.h"
click node_n_core_history "https://github.com/astepaniuk/cad-research/blob/main/src/corecad/model/history/model_history.h"
click node_n_core_registry "https://github.com/astepaniuk/cad-research/blob/main/src/corecad/model/registry.h"
click node_n_core_constraints "https://github.com/astepaniuk/cad-research/blob/main/src/corecad/model/constraint/constraint.h"
click node_n_core_calc "https://github.com/astepaniuk/cad-research/blob/main/src/corecad/calculator/constraints_calculator.h"
click node_n_floor "https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/model/floor.h"
click node_n_wall "https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/model/shape/wall.h"
click node_n_params "https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/model/parameter/parameter.h"
click node_n_generator "https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/generator/default_floor_generator.h"
click node_n_resolver "https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/resolver/point_resolver.h"
click node_n_wall_calc "https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/calculator/wall_calculator.h"
click node_n_main "https://github.com/astepaniuk/cad-research/blob/main/src/gui/main.cpp"
click node_n_window "https://github.com/astepaniuk/cad-research/blob/main/src/gui/main_window/main_window.h"
click node_n_doc "https://github.com/astepaniuk/cad-research/blob/main/src/gui/doc/document.h"
click node_n_views "https://github.com/astepaniuk/cad-research/blob/main/src/gui/view/floor_view.h"
click node_n_editor "https://github.com/astepaniuk/cad-research/blob/main/src/gui/editor/floor_editor.h"
click node_n_snap "https://github.com/astepaniuk/cad-research/blob/main/src/gui/editor/snap/snap_processor.h"
click node_n_pipeline "https://github.com/astepaniuk/cad-research/blob/main/src/gui/editor/calc_pipeline/calc_tools.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_cmake,node_n_vcpkg,node_n_imgui,node_n_freecad toneBlue
class node_n_core_model,node_n_core_history,node_n_core_registry,node_n_core_constraints,node_n_core_calc toneAmber
class node_n_floor,node_n_wall,node_n_params,node_n_generator,node_n_resolver,node_n_wall_calc toneMint
class node_n_main,node_n_window,node_n_doc,node_n_views,node_n_editor,node_n_snap,node_n_pipeline toneRose
```

## Components

### Build & deps

CMake-based build, package management, and bundled third-party libraries.

- [CMake build](https://github.com/astepaniuk/cad-research/blob/main/CMakeLists.txt): build system · Project-wide build orchestration and multi-platform CI configuration. · `CMakeLists.txt`
- [vcpkg](https://github.com/astepaniuk/cad-research/blob/main/vcpkg.json): package manager · Dependency management via manifest-based packages. · `vcpkg.json`
- [ImGui](https://github.com/astepaniuk/cad-research/blob/main/3rd-party/imgui/CMakeLists.txt): ui library · Immediate-mode UI dependency used by the desktop application. · `3rd-party/imgui/CMakeLists.txt`
- [PlaneGCS](https://github.com/astepaniuk/cad-research/blob/main/3rd-party/freecad-planegcs/CMakeLists.txt): solver library · Geometric constraint-solving dependency for sketch-like plan editing. · `3rd-party/freecad-planegcs/CMakeLists.txt`

### CoreCAD

Reusable modeling infrastructure shared by the plan domain and editor.

- [Model base](https://github.com/astepaniuk/cad-research/blob/main/src/corecad/model/model_base.h): core model · Shared object, property, collection, registry, and indexing primitives. · `src/corecad/model/model_base.h`
- [History](https://github.com/astepaniuk/cad-research/blob/main/src/corecad/model/history/model_history.h): undo/redo · Transaction and model-history support for reversible edits. · `src/corecad/model/history/model_history.h`
- [Registries](https://github.com/astepaniuk/cad-research/blob/main/src/corecad/model/registry.h): indexing · Stable registries and trackable pools for model references. · `src/corecad/model/registry.h`
- [Constraints](https://github.com/astepaniuk/cad-research/blob/main/src/corecad/model/constraint/constraint.h): core constraints · Generic constraint types and constraint-taking views. · `src/corecad/model/constraint/constraint.h`
- [Constraint calc](https://github.com/astepaniuk/cad-research/blob/main/src/corecad/calculator/constraints_calculator.h): calculation · Shared calculator utilities for constraint solving and evaluation. · `src/corecad/calculator/constraints_calculator.h`

### Plan domain

Floor-plan model, generation, resolution, and geometry calculation.

- [Floor](https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/model/floor.h): domain entity · Top-level editable floor-plan aggregate. · `src/domain/plan/model/floor.h`
- [Wall](https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/model/shape/wall.h): domain shape · Primary geometric wall shape in the floor model. · `src/domain/plan/model/shape/wall.h`
- [Parameters](https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/model/parameter/parameter.h): editable inputs · Distance and locator parameters used to drive geometry. · `src/domain/plan/model/parameter/parameter.h`
- [Default generator](https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/generator/default_floor_generator.h): domain generator · Creates initial floor content and starting geometry. · `src/domain/plan/generator/default_floor_generator.h`
- [Point resolver](https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/resolver/point_resolver.h): resolution · Resolves abstract locators into concrete points for geometry updates. · `src/domain/plan/resolver/point_resolver.h`
- [Wall calculator](https://github.com/astepaniuk/cad-research/blob/main/src/domain/plan/calculator/wall_calculator.h): geometry calc · Computes wall borders, joins, and intersection-aware wall updates. · `src/domain/plan/calculator/wall_calculator.h`

### GUI/editor

Application shell, document/view layer, and interactive editing pipeline.

- [App entry](https://github.com/astepaniuk/cad-research/blob/main/src/gui/main.cpp): desktop app · Program entry point for the CAD prototype. · `src/gui/main.cpp`
- [Main window](https://github.com/astepaniuk/cad-research/blob/main/src/gui/main_window/main_window.h): shell · Top-level application shell containing workspace and menu. · `src/gui/main_window/main_window.h`
- [Document](https://github.com/astepaniuk/cad-research/blob/main/src/gui/doc/document.h): ui state · Editable document state and document-level services such as snaps. · `src/gui/doc/document.h`
- [Views](https://github.com/astepaniuk/cad-research/blob/main/src/gui/view/floor_view.h): render layer · Floor, walls, constraints, and parameters views with coordinate translation. · `src/gui/view/floor_view.h`
- [Editor](https://github.com/astepaniuk/cad-research/blob/main/src/gui/editor/floor_editor.h): interaction engine · Stateful tool system that interprets input and mutates the model. · `src/gui/editor/floor_editor.h`
- [Snapping](https://github.com/astepaniuk/cad-research/blob/main/src/gui/editor/snap/snap_processor.h): editor assist · Snap builders and processing between mouse input and edits. · `src/gui/editor/snap/snap_processor.h`
- [Calc pipeline](https://github.com/astepaniuk/cad-research/blob/main/src/gui/editor/calc_pipeline/calc_tools.h): orchestration · Sequenced edit-time calculation pipeline coordinating resolver and calculator passes. · `src/gui/editor/calc_pipeline/calc_tools.h`

## Connections

- CMake build → vcpkg: uses · Builds and resolves dependencies through the vcpkg manifest.
- CMake build → ImGui: builds with · The application links against the bundled UI library.
- CMake build → PlaneGCS: builds with · The plan domain links against the bundled geometry solver.
- App entry → Main window: starts · Application entry constructs the top-level shell.
- Main window → Document: hosts · The shell presents the active document and editor context.
- Main window → Views: renders · Workspace and menu coordinate the primary views.
- Main window → Editor: drives · The shell embeds the active floor editor workflow.
- Document → Snapping: contains · Snap state and services live at the document boundary.
- Editor → Snapping: uses · Editing operations consume snapping assistance.
- Editor → Calc pipeline: triggers · Edits flow through an edit-time calculation pipeline.
- Editor → Floor: mutates · Operations update the floor-plan model.
- Snapping → Point resolver: refines to · Snaps help resolve intent into concrete model points.
- Calc pipeline → Point resolver: runs · Pipeline executes point resolution before geometry updates.
- Calc pipeline → Wall calculator: runs · Pipeline sequences wall geometry recalculation.
- Floor → Wall: contains · Floor aggregates wall geometry.
- Floor → Parameters: uses · Floor state is driven by editable parameters.
- Default generator → Floor: creates · Initial content generator seeds a new floor.
- Point resolver → Parameters: resolves · Locator parameters are turned into concrete coordinates.
- Wall calculator → Wall: updates · Calculator recomputes wall borders and joins.
- Wall calculator → Constraint calc: relies on · Domain calculation builds on shared calculator machinery.
- Wall calculator → PlaneGCS: solves with · Geometry constraints are delegated to the external solver.
- Floor → Model base: built on · Domain entities use the shared model base and property system.
- Floor → History: versioned by · Edits are wrapped in undo/redo transactions.
- Floor → Registries: indexed by · Stable registries back model references and lookup.
- Parameters → Constraints: describes · Editable parameters are expressed through generic constraints.
- Views → Model base: reads · Views render shared model state.
- Views → Document: observes · Renderers consume the current document state.