# fougue/mayo architecture

> Architecture diagram of the GitHub repository fougue/mayo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fougue/mayo
- Repository: https://github.com/fougue/mayo

## Overview

##### Project Type & Purpose
- Mayo is a cross‑platform desktop application (Windows, Linux, macOS) plus a command‑line utility for viewing and converting 3D CAD files.
- Written in modern C++ using Qt for UI, OpenCascade for CAD kernel, and various 3rd‑party libraries (fmt, GSL, fast_float, magic_enum, etc.).

##### File Structure Analysis
– Top‑level CMakeLists.txt, README and LICENSE define build and documentation.
– “src” subdivides into:
- app: main GUI application, window management, commands, dialogs, widgets.
- gui: view controllers, document wrappers, event handling.
- cli: command‑line interface entry point and export commands.
- base: core engine – document model, I/O registration, task management, settings, messaging.
- graphics: wrappers around OpenCascade’s rendering, scene/driver management.
- io_*: one directory per file format plugin (STEP, IGES, STL, OBJ, glTF, PLY, DXF, etc.).
- measure: measurement tools for geometry.
- qtbackend & qtcommon: glue between core engine and Qt (settings storage, translators, threading, string conversion).
- 3rdparty: bundled external libs (fmt, fast_float, GSL, etc.).
– tests folder contains unit tests spanning app, base, measure.

##### Key README Insights
– Emphasis on two front‑ends (GUI + CLI) over a shared core.
– Plugin‑style I/O system supporting import/export of many CAD formats.
– Architectural cues: modularity, extensibility, MVC‑style separation, command pattern.

a. Components
1. Front‑ends:
- GUI Application (src/app + src/gui + Qt backend)
- CLI Application (src/cli)
2. Core Engine (src/base):
- Document Manager, Task Manager, Settings, Messaging, I/O System Registry
3. I/O Plugins (src/io_*): one module per file format, registered with I/O System
4. Graphics Engine (src/graphics + OpenCascade): scene graph, object drivers, view controllers
5. Measurement Tools (src/measure)
6. Qt Integration Layer (src/qtbackend, src/qtcommon)
7. 3rd‑Party Libraries (fmt, GSL, fast_float, magic_enum, OpenCascade, Qt)
8. Build & CI: CMake, scripts, GitHub Actions

b. Relationships & Data Flows
- GUI ↔ Core: UI drives document creation, invokes commands, listens to engine events
- CLI → Core: issues batch export commands via I/O System
- Core ↔ I/O Plugins: Core hands over file read/write requests to registered plugins
- Core ↔ Graphics Engine: Core updates scene, issues render/update calls
- Measurement ↔ Core/Graphics: measurement tools query geometry from Core, overlay results in Graphics
- Qt Integration: GUI & Core communicate over Qt signals/slots; settings persisted via Qt backend
- 3rd‑Party: All layers depend on Qt and OpenCascade; core may use fmt/GSL/fast_float

c. Architectural Patterns
- Layered Architecture – Front‑ends, Core, Plugins, External libs
- Plugin Pattern – I/O modules dynamically registered
- MVC/MVP – GUI widgets (view) separate from app_context & document (model)
- Command Pattern – user actions mapped to commands_api
- Observer/Event Bus – messaging and Qt signals/slots for decoupling

d. Technologies & Frameworks
- Build: CMake, custom scripts, GitHub Actions pipelines
- UI: Qt Widgets, .ui forms, qrc resources, i18n via Qt Linguist
- CAD kernel: OpenCascade (BREP, mesh, XDE)
- Logging & formatting: fmt
- Utility libraries: GSL, fast_float, magic_enum

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-Ends
    subgraph "Front-Ends"
        GUIApp["GUI Application"]:::frontend
        CLIApp["CLI Application"]:::frontend
    end

    %% Core Engine
    subgraph "Core Engine"
        DM["Document Manager"]:::core
        TM["Task Manager"]:::core
        ST["Settings"]:::core
        MSG["Messaging"]:::core
        IOReg["I/O System Registry"]:::core
    end

    %% I/O Plugins
    subgraph "I/O Plugins"
        ASSIMP["Assimp Plugin"]:::plugin
        DXF["DXF Plugin"]:::plugin
        GMIO["GMIO Plugin"]:::plugin
        IMAGE["Image Plugin"]:::plugin
        OCC["OpenCascade Plugin"]:::plugin
        OFF["OFF Plugin"]:::plugin
        PLY["PLY Plugin"]:::plugin
    end

    %% Graphics Engine
    subgraph "Graphics Engine"
        Graphics["Graphics Engine"]:::core
    end

    %% Measurement Tools
    subgraph "Measurement Tools"
        Measurement["Measurement Tools"]:::core
    end

    %% Qt Integration
    subgraph "Qt Integration"
        QtBE["Qt Backend"]:::core
        QtCM["Qt Common"]:::core
    end

    %% External Dependencies
    subgraph "External Libraries"
        Qt["Qt"]:::external
        OCCT["OpenCascade"]:::external
        FMT["fmt/GSL/fast_float/magic_enum"]:::external
    end

    %% Build & CI
    subgraph "Build & CI"
        CMake["CMakeLists.txt"]:::external
        CMakeDir["cmake/"]:::external
        Workflows[".github/workflows/"]:::external
        Scripts["scripts/"]:::external
    end

    %% Connections
    GUIApp -->|"invokes commands"| DM
    GUIApp -->|"Observer: Qt signals/slots"| MSG
    CLIApp -->|"batch export commands"| IOReg
    DM -->|"loadModel()/saveModel()"| IOReg
    IOReg -->|"registerPlugin() & readModel()"| ASSIMP
    IOReg -->|"registerPlugin() & readModel()"| DXF
    IOReg -->|"registerPlugin() & readModel()"| GMIO
    IOReg -->|"registerPlugin() & readModel()"| IMAGE
    IOReg -->|"registerPlugin() & readModel()"| OCC
    IOReg -->|"registerPlugin() & readModel()"| OFF
    IOReg -->|"registerPlugin() & readModel()"| PLY
    DM -->|"renderScene()"| Graphics
    Measurement -->|"queryGeometry()"| DM
    Measurement -->|"overlayResults()"| Graphics
    GUIApp -->|"persist settings"| ST
    QtBE -->|"settings storage"| ST
    QtBE -->|"threading/translation"| QtCM
    GUIApp -->|"uses Qt Widgets"| Qt
    QtBE -->|"uses Qt"| Qt
    DM -->|"uses fmt/GSL/fast_float"| FMT
    Graphics -->|"uses OpenCascade"| OCCT

    CMake --> CMakeDir
    CMake --> Workflows
    CMake --> Scripts

    %% Click Events
    click GUIApp "https://github.com/fougue/mayo/tree/develop/src/app"
    click GUIApp "https://github.com/fougue/mayo/tree/develop/src/gui"
    click CLIApp "https://github.com/fougue/mayo/tree/develop/src/cli"
    click DM "https://github.com/fougue/mayo/tree/develop/src/base"
    click ASSIMP "https://github.com/fougue/mayo/tree/develop/src/io_assimp"
    click DXF "https://github.com/fougue/mayo/tree/develop/src/io_dxf"
    click GMIO "https://github.com/fougue/mayo/tree/develop/src/io_gmio"
    click IMAGE "https://github.com/fougue/mayo/tree/develop/src/io_image"
    click OCC "https://github.com/fougue/mayo/tree/develop/src/io_occ"
    click OFF "https://github.com/fougue/mayo/tree/develop/src/io_off"
    click PLY "https://github.com/fougue/mayo/tree/develop/src/io_ply"
    click Graphics "https://github.com/fougue/mayo/tree/develop/src/graphics"
    click Measurement "https://github.com/fougue/mayo/tree/develop/src/measure"
    click QtBE "https://github.com/fougue/mayo/tree/develop/src/qtbackend"
    click QtCM "https://github.com/fougue/mayo/tree/develop/src/qtcommon"
    click ThirdParty "https://github.com/fougue/mayo/tree/develop/src/3rdparty"
    click CMake "https://github.com/fougue/mayo/blob/develop/CMakeLists.txt"
    click CMakeDir "https://github.com/fougue/mayo/tree/develop/cmake/"
    click Workflows "https://github.com/fougue/mayo/tree/develop/.github/workflows/"
    click Scripts "https://github.com/fougue/mayo/tree/develop/scripts/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#039BE5,stroke-width:1px;
    classDef core fill:#D0FFD0,stroke:#388E3C,stroke-width:1px;
    classDef plugin fill:#FFE0B2,stroke:#F57C00,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#757575,stroke-width:1px;
```
