Perastage

Perastage: high-level repository map

Scope (high-level view): this document summarizes the main modules and submodules only. For full file-level detail, use rg --files or your IDE tree view.

This page is a concise navigational reference. The authoritative ownership and dependency rules live in Architecture, while Repository Layout owns the detailed human-readable path and root-file map.

This map is aligned with the terminology used in README.md and docs/developer/architecture.md: functional modules (app, cli, core, gui, viewer2d, viewer3d, viewer_common, models, mvr), packaged runtime content (library, resources), packaging and build support (cmake, scripts, packaging, .github/workflows), vendored dependencies (third_party), and tests/docs (tests, docs).

Top-level structure

Perastage/
|-- main.cpp                     # Minimal wxWidgets application-entry wiring.
|-- CMakeLists.txt               # Root target creation, build orchestration, and module registration.
|-- CMakePresets.json            # Supported local configure/build presets.
|-- setup.sh                     # Stable Linux/WSL setup launcher.
|-- setup_windows.ps1            # Stable Windows setup launcher.
|-- README.md                    # Product overview, features, and entry links.
|-- docs/                        # Canonical docs/user manual, developer/reference docs, and website assets.
|-- AGENTS.md                    # Repository guidance for automated coding agents.
|-- VERSION                      # Single project version source.
|-- app/                         # Application lifecycle and startup/bootstrap composition.
|   `-- CMakeLists.txt           # Explicit App source registration.
|-- cli/                         # Dedicated headless command-line executable and grammar.
|   `-- CMakeLists.txt           # Explicit CLI target and source ownership.
|-- cmake/                       # Focused build modules, templates, and helper scripts.
|   `-- platform/                # Platform target-configuration dispatcher and OS-specific owners.
|-- scripts/                     # Setup implementations and repository/build utilities.
|   |-- linux/                   # Implementation behind the stable root setup.sh launcher.
|   `-- windows/                 # Implementation behind the stable root setup_windows.ps1 launcher.
|-- core/                        # Shared business logic and cross-cutting services.
|   |-- layouts/                 # Printable layout/page management.
|   `-- print/                   # Printing and PDF/table export helpers.
|-- gui/                         # wxWidgets UI (main window, panels, dialogs).
|   |-- mainwindow/              # Main-window workflows, IDs, and controllers.
|   `-- fixturetable/            # Fixture-table parsing, editing, and column logic.
|-- viewer2d/                    # 2D renderer and export-related utilities.
|   `-- pdf/                     # PDF encoding/writing and drawing primitives.
|-- viewer3d/                    # 3D renderer, camera, loaders, and pipeline.
|   |-- render/                  # Render passes and OpenGL pipeline.
|   |-- culling/                 # Visibility and bounds systems.
|   |-- picking/                 # Selection and interaction systems.
|   |-- labels/                  # Label rendering systems.
|   |-- resources/               # Render-resource synchronization.
|   `-- interfaces/              # Render/selection context contracts.
|-- viewer_common/               # Shared viewer utilities used across viewer modules.
|-- models/                      # Scene data structures (fixtures/trusses/hoists/objects/layers).
|   `-- CMakeLists.txt           # Explicit model source registration for the application target.
|-- mvr/                         # MVR format import/export modules and MVR-xchange networking.
|   `-- CMakeLists.txt           # Explicit MVR and MVR-xchange source registration.
|-- packaging/                   # Installer, desktop integration, and package metadata.
|-- tests/                       # Automated tests and lightweight checks.
|-- tools/mcp/                   # Standalone Rust stdio MCP adapter over perastage-cli.
|-- library/                     # Packaged runtime content (fixtures, trusses, etc.).
|-- resources/                   # Visual/platform resources (icons, fonts, .rc).
|-- third_party/                 # Vendored third-party headers.
|-- licenses/                    # Third-party license files.
`-- .github/workflows/           # GitHub Actions workflows.

Modules and responsibilities

  • app/: wxWidgets application lifecycle, startup orchestration, external-open routing, diagnostics coordination, and shutdown composition.
  • cli/: standard-C++ command-line entry point and stable technical grammar, without GUI lifecycle dependencies.
  • core/: project/config services, rider/PDF import helpers, auto-patch logic, layout/print support, and persistence/export utilities.
  • gui/: main UI composition and editing/visualization tools (tables, panels, dialogs, menus).
  • viewer2d/: 2D plan visualization and command/resource generation for printing/export.
  • viewer3d/: real-time 3D visualization, geometry loading (GDTF/3DS/GLB), and render pipeline.
  • viewer_common/: shared viewer-side helpers that should not belong exclusively to either the 2D or 3D viewer.
  • models/: core scene model (fixtures, trusses, hoists/supports, objects, layers).
  • mvr/: inbound/outbound integration with the MVR ecosystem, including MVR-xchange support.
  • packaging/: platform packaging metadata, installer scripts, and desktop integration files.
  • cmake/platform/: Windows and macOS target/build configuration plus the explicit Linux target-configuration boundary, selected through one dispatcher.

Critical files (explicit exception to high-level granularity)

  • main.cpp: minimal application-entry wiring and sole root C/C++ entry point. The App-owned MyApp declaration and implementation live under app/; see the implemented ownership boundary in docs/developer/architecture.md.
  • CMakeLists.txt: primary build orchestration.
  • CMakePresets.json: supported local configure/build presets.
  • README.md: functional/documentation reference.
  • docs/developer/architecture.md: authoritative architecture ownership and dependency rules.
  • docs/developer/repository_layout.md: authoritative human-readable repository layout.
  • docs/developer/documentation_policy.md: documentation organization and synchronization rules.

Maintenance guidance

  • Keep module/submodule names consistent with README.md, docs/developer/architecture.md, and docs/developer/repository_layout.md.
  • Avoid listing all individual files except truly critical entry points.
  • If repository layout changes, update this document in the same PR.
  • If a new top-level source module is introduced, update the architecture guard scripts under tests/ when appropriate.
  • Every top-level application source module owns an explicit local CMake source list; the root does not normally register feature implementations, and no recursive source discovery is used.
  • repository_structure_baseline.json is the authoritative machine-readable contract for source-module classification and root module registration.
  • New source modules must align that contract, explicit module and root CMake registration, architecture/layout documentation, and required guard inventories.
  • Root project sources are limited to documented entry-point exceptions, and developer-local presets, build trees, and IDE state must remain untracked.
Back to top