# xaos-project/xaos architecture

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

- Interactive diagram: https://gitdiagram.com/xaos-project/xaos
- Repository: https://github.com/xaos-project/xaos

## Overview

##### Project type and purpose
- XaoS is a native C++/Qt “full-stack” desktop application (with an optional web version) for real-time interactive fractal zooming.
- The README describes its core: smooth zooming into fractals, multiple fractal formulas, coloring modes, autopilot, i18n, packaging and web deployment.

##### File structure
- Top level:
- .github + workflows → CI/build definitions
- CMakeLists.txt, XaoS.pro → build system (CMake & QMake)
- src/ → primary C++ code, subdivided into:
– engine/ (fractal computation core)
– ui/ (Qt widgets, main window, dialogs, resources)
– util/ (image I/O, threading, palettes, error handling)
– formeval/ and sffe/ (specialized math libraries/plugins)
- i18n/ and catalogs/ → translation sources (.ts) and compiled catalogs (.cat)
- installer/ and tools/ → packaging scripts, installer definitions
- examples/, tutorial/, doc/ → data and documentation
- Patterns:
- Layered architecture (UI → Engine → Utility)
- Plugin-like math modules (formeval, sffe)
- Resource bundling (Qt .qrc, .ts/.cat for i18n)
- Automated builds and packaging (GitHub Actions, scripts)

##### README for additional insights
- Confirms Qt Widgets usage, cross-platform targets, web app variant since v4.3

##### Elements
- Component blocks labeled: “UI Layer,” “Engine Layer,” “Math Plugins,” “Utility Layer,” “Data/Resources,” “Build & Packaging,” “Web App”
- User Input → UI → Engine → Utility → Engine → UI → Display
- Source files → Build System → Binaries & Resources → Installer/Web
- .ts files → Qt Linguist → .cat → UI
- UI components (blue), compute core (green), utility (yellow), data/resources (orange), build pipeline (gray), external/web (purple)

##### Final advice
- Be detailed: break down engine submodules (filters, zoom, formulas), UI subcomponents (main window, fractal widget, dialogs)
- Don’t overthink: represent every distinct directory/component in src/ and tools/ as its own block or sub-block to capture completeness

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User flow
    UserInput["User Input"]:::external
    Display["Display Output"]:::external

    %% Layers and components
    subgraph "UI Layer"
        direction TB
        MainWindow["MainWindow"]:::ui
        FractalWidget["FractalWidget"]:::ui
        Dialogs["Dialogs"]:::ui
        QtResource["Qt Resource System (.qrc)"]:::ui
    end

    subgraph "Engine Layer"
        direction TB
        FractalCore["Fractal Computation Core"]:::engine
        Formulas["Formulas & Filters"]:::engine
        ZoomRotate["Zoom & Rotate"]:::engine
    end

    subgraph "Utility Layer"
        direction TB
        ImageIO["Image I/O"]:::util
        Threading["Threading & Timing"]:::util
        Palette["Palette Generation"]:::util
        ErrorHandling["Error Handling"]:::util
    end

    subgraph "Math Plugins"
        direction TB
        FormEval["formeval Plugin"]:::plugin
        SFFE["sffe Plugin"]:::plugin
    end

    subgraph "Data/Resources"
        direction TB
        TransTS["Translations (.ts)"]:::data
        Linguist["Qt Linguist"]:::data
        CatalogCAT["Compiled Catalogs (.cat)"]:::data
        Examples["Examples (.xpf/.xaf)"]:::data
        Tutorials["Tutorials"]:::data
        DesktopMeta["Desktop Metadata"]:::data
    end

    subgraph "Build & Packaging"
        direction TB
        BuildSystem["Build System\n(CMake/QMake)"]:::build
        CI["CI (GitHub Actions)"]:::build
        InstallerScripts["Installer Scripts"]:::build
        PackagingTools["Packaging Tools"]:::build
    end

    subgraph "Web App Variant"
        direction TB
        WebBuild["Web Build Scripts"]:::web
        WebAssets["Web Assets (WASM/JS)"]:::web
    end

    %% Data flows
    UserInput -->|"user actions"| MainWindow
    MainWindow -->|"render call"| FractalWidget
    FractalWidget -->|"compute frame"| FractalCore
    FractalCore -->|"needs I/O/palette"| ImageIO
    FractalCore --> Threading
    FractalCore --> Palette
    ImageIO --> FractalCore
    Threading --> FractalCore
    Palette --> FractalCore
    FractalCore -->|"frame buffer"| FractalWidget
    FractalWidget --> Display

    FractalCore --> FormEval
    FractalCore --> SFFE

    TransTS -->|"translate"| Linguist
    Linguist --> CatalogCAT
    CatalogCAT --> MainWindow

    %% Build pipeline
    BuildSystem --> CI
    CI --> InstallerScripts
    InstallerScripts --> PackagingTools

    %% Web pipeline
    WebBuild --> WebAssets
    WebAssets -->|"loads"| FractalCore
    WebAssets --> MainWindow

    %% Component mappings (click events)
    click MainWindow "https://github.com/xaos-project/xaos/tree/master/src/ui/"
    click FractalWidget "https://github.com/xaos-project/xaos/tree/master/src/ui/"
    click Dialogs "https://github.com/xaos-project/xaos/tree/master/src/ui/"
    click QtResource "https://github.com/xaos-project/xaos/blob/master/src/ui/XaoS.qrc"
    click FractalCore "https://github.com/xaos-project/xaos/tree/master/src/engine/"
    click Formulas "https://github.com/xaos-project/xaos/tree/master/src/engine/"
    click ZoomRotate "https://github.com/xaos-project/xaos/tree/master/src/engine/"
    click ImageIO "https://github.com/xaos-project/xaos/tree/master/src/util/"
    click Threading "https://github.com/xaos-project/xaos/tree/master/src/util/"
    click Palette "https://github.com/xaos-project/xaos/tree/master/src/util/"
    click ErrorHandling "https://github.com/xaos-project/xaos/tree/master/src/util/"
    click FormEval "https://github.com/xaos-project/xaos/tree/master/src/formeval/"
    click SFFE "https://github.com/xaos-project/xaos/tree/master/src/sffe/"
    click TransTS "https://github.com/xaos-project/xaos/tree/master/i18n/"
    click CatalogCAT "https://github.com/xaos-project/xaos/tree/master/catalogs/"
    click Examples "https://github.com/xaos-project/xaos/tree/master/examples/"
    click Tutorials "https://github.com/xaos-project/xaos/tree/master/tutorial/"
    click DesktopMeta "https://github.com/xaos-project/xaos/tree/master/xdg/"
    click BuildSystem "https://github.com/xaos-project/xaos/blob/master/CMakeLists.txt"
    click CI "https://github.com/xaos-project/xaos/blob/master/.github/workflows/build.yml"
    click InstallerScripts "https://github.com/xaos-project/xaos/tree/master/installer/"
    click PackagingTools "https://github.com/xaos-project/xaos/tree/master/tools/"
    click WebBuild "https://github.com/xaos-project/xaos/tree/master/tools/"
    click WebAssets "https://github.com/xaos-project/xaos/tree/master/src/ui/"

    %% Styles
    classDef ui fill:#D0E4FD,stroke:#0366d6,color:#0366d6;
    classDef engine fill:#D8F5D3,stroke:#28a745,color:#28a745;
    classDef util fill:#FFF3CD,stroke:#FFCD39,color:#856404;
    classDef plugin fill:#E2F0CB,stroke:#6AA84F,color:#38761D;
    classDef data fill:#FDE2C4,stroke:#F4B183,color:#A65E2E;
    classDef build fill:#E0E0E0,stroke:#636363,color:#212529;
    classDef web fill:#E5D7F2,stroke:#8E44AD,color:#6C3483;
    classDef external fill:#FFFFFF,stroke:#888888,color:#888888,stroke-dasharray: 5 5;
```
