# stackotter/swift-cross-ui architecture

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

- Interactive diagram: https://gitdiagram.com/stackotter/swift-cross-ui
- Repository: https://github.com/stackotter/swift-cross-ui

## Overview

##### Main Components
- Core Framework Module: Represent the central SwiftCrossUI library which includes the core API for building views, managing state (e.g., State, Binding, Published), and constructing scene graphs (the view hierarchy management).
- Backend Modules: Illustrate the various backends that the framework supports. These include:
- DefaultBackend (which adapts to the target OS)
- AppKitBackend (macOS)
- UIKitBackend (iOS/tvOS)
- WinUIBackend (Windows)
- GtkBackend & Gtk3Backend (Linux, plus macOS/Windows for Gtk3)
- Other experimental/alternative backends (e.g., LVGLBackend, CursesBackend, QtBackend)
- Examples: Include an examples category which demonstrates how client applications (e.g., CounterExample, NavigationExample, etc.) make use of the framework.
- Auxiliary Modules: Note the additional support components such as code generators (GtkCodeGen), hot reloading macros, custom widgets (GtkCustomWidgets, SwiftCrossUI/ViewGraph), and tests.

##### Relationships & Interactions
- The Core Framework is the center of the architecture – it exposes the API for developers.
- The front-end usage by client apps (shown in Examples) will be built on top of SwiftCrossUI and use the APIs for Views, Scenes, and State management. Illustrate how an Example app (like the CounterExample) interacts with the Core Framework which in turn interfaces with the selected backend.
- Additionally, include support flows such as how hot reloading macros or code generation modules feed into the build or runtime system.

##### Architectural Patterns & Design Principles
- Separation of concerns: the UI logic is abstracted in the core framework while each backend encapsulates the platform-specific details.
- API resemblances to SwiftUI (using concepts such as Scenes, Views, and State) but with customization points to adapt to different platforms.
- Use of modular design by placing each backend in its own submodule, so it’s clear that adding a new backend only requires interfacing with the common API of SwiftCrossUI.

##### Specify Relevant Technologies
- Language: Swift (5.10+)
- Build/Dependency Tools: Swift Package Manager (as shown in Package.swift), along with scripts and Dockerfile for containerized builds.
- CI/CD & Linting: GitHub workflows for building on macOS, Linux, Windows; SwiftLint and SwiftFormat configurations.
- Integration of external libraries or system dependencies for certain backends (e.g., GTK 3/4 for GtkBackend/Gtk3Backend).

##### Suggested Elements
- Annotation/Notes: Optionally add brief notes next to each component to mention its purpose (e.g., “Handles view construction and state management”, “Maps APIs to native OS UI frameworks”).

- Similarly, list out the backends as separate nodes with critical dependencies (for example, showing that DefaultBackend conditionally selects a specific backend at compile-time/runtime).

– At the top/center, show the SwiftCrossUI core layer.
– Branching from it, illustrate the different backend modules.
– Connect an “Example App Layer” that shows how client applications plug into the system.
– Optionally, annotate peripheral components like CI/CD pipelines or code generation tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD & Build Tools Layer
    subgraph "CI/CD & Build Tools"
        CICD["CI/CD & Build Tools"]:::cicd
    end

    %% Auxiliary Modules Layer
    subgraph "Auxiliary Modules"
        CodeGen["GtkCodeGen"]:::auxiliary
        HotReload["HotReloading Macros"]:::auxiliary
        CustomWidgets["GtkCustomWidgets"]:::auxiliary
        CustomWidgetsInclude["GtkCustomWidgets/include"]:::auxiliary
    end

    %% Client Examples Layer
    subgraph "Client Examples"
        Examples["Examples"]:::examples
    end

    %% SwiftCrossUI Core Layer
    subgraph "SwiftCrossUI Core"
        Core["SwiftCrossUI Core"]:::core
        Views["Views"]:::core
        Scenes["Scenes"]:::core
        State["State Management"]:::core
        ViewGraph["ViewGraph"]:::core
    end

    %% Backend Modules Layer
    subgraph "Backend Modules"
        Default["DefaultBackend"]:::backend
        AppKit["AppKitBackend"]:::backend
        UIKit["UIKitBackend"]:::backend
        WinUI["WinUIBackend"]:::backend
        Gtk["GtkBackend"]:::backend
        Gtk3["Gtk3Backend"]:::backend
        LVGL["LVGLBackend"]:::backend
        Curses["CursesBackend"]:::backend
        Qt["QtBackend"]:::backend
    end

    %% Internal breakdown of Core Framework
    Core --> Views
    Core --> Scenes
    Core --> State
    Core --> ViewGraph

    %% CI/CD & Auxiliary & Examples feeding into Core
    CICD -->|"integrates"| Core
    CodeGen -->|"supports"| Core
    HotReload -->|"supports"| Core
    CustomWidgets -->|"provides widgets"| Core
    CustomWidgetsInclude -->|"provides headers"| Core
    Examples -->|"uses"| Core

    %% Core's dependency on Backend Modules
    Core -->|"selects"| Default
    Core -->|"selects"| AppKit
    Core -->|"selects"| UIKit
    Core -->|"selects"| WinUI
    Core -->|"selects"| Gtk
    Core -->|"selects"| Gtk3
    Core -->|"selects"| LVGL
    Core -->|"selects"| Curses
    Core -->|"selects"| Qt

    %% Click Events
    click Core "https://github.com/stackotter/swift-cross-ui/tree/main/Sources/SwiftCrossUI"
    click Default "https://github.com/stackotter/swift-cross-ui/blob/main/Sources/DefaultBackend/DefaultBackend.swift"
    click AppKit "https://github.com/stackotter/swift-cross-ui/blob/main/Sources/AppKitBackend/AppKitBackend.swift"
    click UIKit "https://github.com/stackotter/swift-cross-ui/blob/main/Sources/UIKitBackend/UIKitBackend.swift"
    click WinUI "https://github.com/stackotter/swift-cross-ui/blob/main/Sources/WinUIBackend/WinUIBackend.swift"
    click Gtk "https://github.com/stackotter/swift-cross-ui/tree/main/Sources/Gtk"
    click Gtk3 "https://github.com/stackotter/swift-cross-ui/blob/main/Sources/Gtk3Backend/Gtk3Backend.swift"
    click LVGL "https://github.com/stackotter/swift-cross-ui/blob/main/Sources/LVGLBackend/LVGLBackend.swift"
    click Curses "https://github.com/stackotter/swift-cross-ui/blob/main/Sources/CursesBackend/CursesBackend.swift"
    click Qt "https://github.com/stackotter/swift-cross-ui/blob/main/Sources/QtBackend/QtBackend.swift"
    click Examples "https://github.com/stackotter/swift-cross-ui/tree/main/Examples"
    click CodeGen "https://github.com/stackotter/swift-cross-ui/tree/main/Sources/GtkCodeGen"
    click HotReload "https://github.com/stackotter/swift-cross-ui/tree/main/Sources/HotReloadingMacrosPlugin"
    click CustomWidgets "https://github.com/stackotter/swift-cross-ui/tree/main/Sources/GtkCustomWidgets"
    click CustomWidgetsInclude "https://github.com/stackotter/swift-cross-ui/tree/main/Sources/GtkCustomWidgets/include"
    click CICD "https://github.com/stackotter/swift-cross-ui/blob/main/.github"

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef backend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef examples fill:#afa,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#ff9,stroke:#333,stroke-width:2px;
    classDef cicd fill:#fbb,stroke:#333,stroke-width:2px;
```
