# ehb54/ultrascan3 architecture

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

- Interactive diagram: https://gitdiagram.com/ehb54/ultrascan3
- Repository: https://github.com/ehb54/ultrascan3

## Overview

##### Main Components
- GUI Layer: The “gui” directory and related Qt project files (such as the .pro files) represent the front-end interface. This layer handles user interactions, rendering of data and user commands.
- Utility and Shared Libraries: The “utils” directory and other library project files (e.g., library.pri) provide common functions and shared routines (like file I/O, math utilities, configuration, MPI support, etc.) that are used across the multiple application modules.
- Container and Build Infrastructure: The “admin” directory with subfolders for Docker, CI/CD workflows (GitHub workflows, CodeQL analysis) illustrates how the project is built and tested in both local and containerized environments.
- Documentation and Testing: “doc”, “test” (including manual and Doxygen documentation) are important for understanding and verifying system functionalities.
- External Dependencies: Technologies such as Qt5 (for the graphical interface), Qwt (for plotting), and Eigen (for math and linear algebra) are vital system components.

##### Relationships and Data Flow
- The GUI layer communicates with the underlying backend modules through Qt signal/slot mechanisms. User interactions trigger commands that are processed by the different “us_*” application modules.
- Shared libraries (under “utils” and similar folders) are used by many executables and serve as common backend services – e.g., reading data files, interfacing with databases, performing advanced mathematical computations and simulations.
- The build system and container scripts are separate components for development/deployment and do not affect runtime but are essential for continuous integration, deployment, and maintenance.

##### Architectural Patterns and Principles
- Modularity: The large number of executables and libraries signifies strong modular separation by functionality.
- MVC-like Separation: The use of a dedicated “gui” directory for the front end, separate from processing units (“programs” and “utils”), suggests a separation of user interface and business logic.
- Use of Standard Build and Versioning Tools: Files like CMakeLists.txt, .pro files, and Dockerfiles indicate that the project follows standardized build and continuous integration patterns.
- Containerization: The project supports containerized development (via Docker) to encapsulate the build environment, which is key for reproducible builds and deployment.

##### Elements

■ The UI layer (with “gui” and any associated resources)
■ The Application modules (multiple “us_” executables grouped perhaps by function – data analysis, simulation, visualization, etc.)
■ The supporting utilities and common libraries (group them as “Utils/Shared Libraries”)
■ The build/integration environment (admin, Docker, CI workflows)
■ External libraries/dependencies (Qt5, Qwt, Eigen)
- Reading from input files and writing output (the project expects data input, processing and then visualization output).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer: GUI Layer"
        GUI["GUI Interface"]:::gui
    end

    subgraph "Application Modules"
        US["us Executable"]:::app
        US_2dplot["us_2dplot Executable"]:::app
        US_Buffer["us_buffer Executable"]:::app
        US_ModelMetrics["us_modelmetrics Executable"]:::app
    end

    subgraph "Shared Utilities"
        Utils["Shared Libraries"]:::utils
    end

    subgraph "Dev & Deployment"
        Build["Build/Container Infrastructure"]:::build
    end

    subgraph "Documentation & Testing"
        Docs["Documentation"]:::docs
        Tests["Test Suites"]:::docs
    end

    subgraph "External Dependencies"
        External["External Dependencies<br/>(Qt5, Qwt, Eigen)"]:::external
    end

    %% GUI to Core Modules via Qt signal/slot mechanism
    GUI -->|"QtSignals/Slots"| US
    GUI -->|"QtSignals/Slots"| US_2dplot
    GUI -->|"QtSignals/Slots"| US_Buffer
    GUI -->|"QtSignals/Slots"| US_ModelMetrics

    %% Core Modules calling shared utilities
    US -->|"calls"| Utils
    US_2dplot -->|"calls"| Utils
    US_Buffer -->|"calls"| Utils
    US_ModelMetrics -->|"calls"| Utils

    %% Build system builds and deploys the components
    Build -->|"builds"| GUI
    Build -->|"builds"| US
    Build -->|"builds"| US_2dplot
    Build -->|"builds"| US_Buffer
    Build -->|"builds"| US_ModelMetrics
    Build -->|"builds"| Utils

    %% Documentation and Testing validate each core module
    US -->|"documented"| Docs
    US_2dplot -->|"documented"| Docs
    US_Buffer -->|"documented"| Docs
    US_ModelMetrics -->|"documented"| Docs

    US -->|"tested"| Tests
    US_2dplot -->|"tested"| Tests
    US_Buffer -->|"tested"| Tests
    US_ModelMetrics -->|"tested"| Tests

    %% External Dependencies provide essential libraries and frameworks
    External -->|"provides"| GUI
    External -->|"provides"| US
    External -->|"provides"| US_2dplot
    External -->|"provides"| US_Buffer
    External -->|"provides"| US_ModelMetrics

    %% Click Events
    click GUI "https://github.com/ehb54/ultrascan3/tree/master/gui"
    click US "https://github.com/ehb54/ultrascan3/tree/master/programs/us"
    click US_2dplot "https://github.com/ehb54/ultrascan3/tree/master/programs/us_2dplot"
    click US_Buffer "https://github.com/ehb54/ultrascan3/tree/master/programs/us_buffer"
    click US_ModelMetrics "https://github.com/ehb54/ultrascan3/tree/master/programs/us_modelmetrics"
    click Utils "https://github.com/ehb54/ultrascan3/tree/master/utils"
    click Build "https://github.com/ehb54/ultrascan3/tree/master/admin"
    click Docs "https://github.com/ehb54/ultrascan3/tree/master/doc"
    click Tests "https://github.com/ehb54/ultrascan3/tree/master/test"
    click External "https://github.com/ehb54/ultrascan3/blob/master/gui.pri"

    %% Styles
    classDef gui fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
    classDef app fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef utils fill:#FFA07A,stroke:#FF4500,stroke-width:2px;
    classDef build fill:#DDA0DD,stroke:#800080,stroke-width:2px;
    classDef docs fill:#FFFFE0,stroke:#FFD700,stroke-width:2px;
    classDef external fill:#F08080,stroke:#B22222,stroke-width:2px;
```
