# uvvis-bira-iasb/qdoas architecture

> Architecture diagram of the GitHub repository uvvis-bira-iasb/qdoas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uvvis-bira-iasb/qdoas
- Repository: https://github.com/uvvis-bira-iasb/qdoas

## Overview

##### Project type and overall purpose
- QDOAS is a cross-platform software suite for trace gas retrieval from UV-Visible spectral measurements using the DOAS method. It comes with a rich graphical user interface (GUI) as well as several standalone command‐line tools for specialized processing (convolution, ring effect calculations, undersampling, and batch processing with doas_cl).
- The software supports multiple spectral file formats and incorporates sophisticated analysis and calibration techniques, indicating a complex, multi-module application with a clear separation between user interaction (GUI) and backend processing.

##### Key modules and their organization from the file structure
- Top-level directories such as “qdoas”, “convolution”, “ring”, “usamp”, and “cmdline” indicate how functionality is separated into different executables or modules.
- Directories like “engine”, “common”, and “mediator” house core algorithms, business logic, helpers, and inter-module communication. They represent the backbone of the DOAS data processing and analysis.
- Additional directories (e.g., “config”, “custom-overlay”, “dirent”) and build/configuration files (CMakeLists.txt, CMakePresets.json, vcpkg configuration) show integration with external libraries and environment setup.
- The project also provides separate help resources under the “qdoas/Help” folder, emphasizing user support and documentation integration.

a. Main Components:
- User Interface Layer (GUI): Represented by the QDOAS executable in the “qdoas” directory. It handles user interactions, displays multi-page panels, and interacts with on-line help.
- Command-Line Tools: Include “doas_cl” for batch processing, “convolution” for real-time cross-section convolution/filtering, “ring” for ring effect calculations, and “usamp” for undersampling.
- Core Processing Engine: Represented by the “engine”, “common”, and “mediator” directories. This layer implements the algorithms for spectral analysis, calibration, and data handling.
- External Dependencies & Libraries: Include Qt and Qwt (for GUI and plotting), CODA, HDF4/HDF5, NetCDF, Boost, Eigen, and libxml++. These should appear as external component blocks from which the system “pulls” functionality.
- Build & Configuration Infrastructure: CMake files, vcpkg configuration, and other build scripts indicate how modules are integrated at compile time.

b. Relationships and Interactions:
- Similarly, show interactions from the command-line tool (doas_cl) with the configuration files and engine routines.
- Out communication with external libraries. For instance, indicate that the UI layer uses the Qt toolkit, while data processing modules invoke specialized libraries for netCDF and HDF support.
- Demonstrate that core modules in “engine”, “common”, and “mediator” are shared across multiple tools (i.e., convolution, ring, usamp, and the GUI).

c. Highlighting Architectural Patterns and Design Principles:
- The separation of concerns is clear: the project is divided into distinct executables for different functionalities while sharing common backend processing libraries.
- Modular design is evident, where each tool (GUI, convolution, ring, usamp, doas_cl) encapsulates specific functionality but relies on a common core.
- That there is a layered architecture—an interface layer (GUI/CLI), a processing layer (engine and common modules), and an infrastructure layer (configuration, build scripts, external libraries).

d. Technologies & Frameworks:

- Bidirectional communication for configuration updates between tools and a central config handler.
- Relationships and dependencies (e.g., between the mediator and the engine, or between the core routines and the external libraries) are clearly annotated.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraph: User Interface Layer
    subgraph "User Interface Layer"
        GUI["QDOAS GUI"]:::ui
    end

    %% Subgraph: Command-Line Tools
    subgraph "Command-Line Tools"
        DoasCL["Command-Line (doas_cl)"]:::cli
        ConvolutionTool["Convolution Tool"]:::cli
        RingTool["Ring Effect Tool"]:::cli
        UsampTool["Undersampling Tool"]:::cli
    end

    %% Subgraph: Core Processing Engine
    subgraph "Core Processing Engine"
        EngineAlg["Algorithms"]:::engine
        EngineHelp["Helpers & Business Logic"]:::engine
        EngineMed["Inter-Module Communication"]:::engine
    end

    %% Subgraph: Build & Configuration Infrastructure
    subgraph "Build & Configuration"
        BuildConfig["Build & Config Infrastructure"]:::build
    end

    %% Subgraph: External Dependencies
    subgraph "External Dependencies"
        ExtGUILib["GUI Libraries (Qt & Qwt)"]:::external
        ExtSciLib["Scientific Libraries (Boost, Eigen, CODA, HDF, NetCDF, libxml++)"]:::external
    end

    %% Relationships from UI Layer to Core Processing Engine
    GUI -->|"triggers"| EngineAlg
    GUI -->|"triggers"| EngineHelp
    GUI -->|"triggers"| EngineMed

    %% Relationships from Command-Line Tools to Core Processing Engine
    DoasCL -->|"executes"| EngineAlg
    ConvolutionTool -->|"uses"| EngineAlg
    RingTool -->|"uses"| EngineAlg
    UsampTool -->|"uses"| EngineAlg

    %% Relationships to Build & Config Infrastructure
    DoasCL -.->|"configures"| BuildConfig
    ConvolutionTool -.->|"configures"| BuildConfig
    RingTool -.->|"configures"| BuildConfig
    UsampTool -.->|"configures"| BuildConfig
    BuildConfig -->|"integrates"| EngineAlg

    %% External Dependencies support
    ExtGUILib -->|"supports"| GUI
    ExtSciLib -->|"supports"| EngineAlg
    ExtSciLib -->|"supports"| EngineHelp
    ExtSciLib -->|"supports"| EngineMed

    %% Classes for node styles
    classDef ui fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef cli fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef engine fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef build fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click GUI "https://github.com/uvvis-bira-iasb/qdoas/blob/master/qdoas/CWMain.cpp"
    click DoasCL "https://github.com/uvvis-bira-iasb/qdoas/blob/master/cmdline/cmdline.cpp"
    click ConvolutionTool "https://github.com/uvvis-bira-iasb/qdoas/blob/master/convolution/convolution.cpp"
    click RingTool "https://github.com/uvvis-bira-iasb/qdoas/blob/master/ring/ringtool.cpp"
    click UsampTool "https://github.com/uvvis-bira-iasb/qdoas/blob/master/usamp/usamptool.cpp"
    click EngineAlg "https://github.com/uvvis-bira-iasb/qdoas/tree/master/engine/"
    click EngineHelp "https://github.com/uvvis-bira-iasb/qdoas/tree/master/common/"
    click EngineMed "https://github.com/uvvis-bira-iasb/qdoas/tree/master/mediator/"
    click BuildConfig "https://github.com/uvvis-bira-iasb/qdoas/tree/master/config/"
```
