# helbertgs/openswiftui architecture

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

- Interactive diagram: https://gitdiagram.com/helbertgs/openswiftui
- Repository: https://github.com/helbertgs/openswiftui

## Overview

##### Project Type and Purpose
- OpenSwiftUI is an open-source Swift Package that re-implements Apple’s SwiftUI framework for multiple platforms (macOS/AppKit, Windows, Linux via OpenGL/OpenUIKit).
- It’s a developer library (not a client/server or full-stack app) whose primary goal is to let you declare UIs, state, and event handling in a declarative, cross-platform way.

##### High‐Level Components
- Package Manager & CI
- Package.swift – defines the SwiftPM package and module dependencies
- .github/workflows – CI pipelines for Windows and Ubuntu builds/tests
- Core Framework (module: OpenSwiftUI)
- Domain-layer feature modules
– Accessibility
– Animations
– App Structure (App, Scenes, Windows, Documents, Widgets)
– Data and Storage (environment values, model data, persistent storage, preferences)
– Event Handling (gestures, input events, system events)
– View Layout & View Tree (layout engine, custom layouts, graph, tree)
- Integration & Platform Abstraction
– Framework Integration (AppKit delegators, etc.)
– Platforms (OpenGL host controllers, platform entrypoints)
- Sample Application
- Sources/OpenSwiftUISample/MyApp.swift – example app that imports and exercises OpenSwiftUI

##### Interactions and Dependencies
- Sample App → depends on Core Framework API (imports OpenSwiftUI)
- Feature Modules → depend on Core View Tree & Layout sub-modules
- Feature Modules → use Data & Storage for state propagation and environment values
- Feature Modules → use Event Handling for gestures and system input
- Core Framework → calls into Framework Integration and Platforms layers for OS-specific rendering and event delivery

##### Architectural Patterns and Principles
- Layered Modular Architecture: clear separation between
1. API (Views, Modifiers, Accessibility, Animations)
2. Core Engine (View Tree, Layout, Data Flow)
3. Integration Layer (bridges to AppKit/OpenGL/OpenUIKit)
- Feature-based organization: each major SwiftUI concept is its own directory/module
- Declarative, functional style: uses value types, protocol conformance (View, Animatable, etc.) and property wrappers

##### What
- Sample App
- OpenSwiftUI Core Modules (grouped by domain)
- Core Engine (View Tree & Layout)
- Framework Integration & Platform Abstraction
- SwiftPM & CI
- "imports"/"depends on" from Sample to Core Modules
- internal dependencies: Feature Modules → Core Engine; Feature Modules → Event Handling/Data Storage
- Core Framework → Platform layer → OS APIs (AppKit/OpenGL)
- Blue: public API modules (Views, App Structure, Accessibility, etc.)
- Green: core engine modules (View Tree, Layout, Data Flow)
- Orange: integration layers (Framework Integration, Platforms)
- Grey: build/CI (Package.swift, workflows)
- Labels for
- Each module’s responsibility
- Data flows (e.g., “ViewBuilder → Layout Engine → Render via OpenGL”)
- Extension points (“Custom Layouts”, “Custom Views”)

– Public API Modules (Accessibility, Animations, App Structure, Views, Event Handling, Data & Storage)
– Core Engine (View Tree, Layout)
d. At the bottom, show “OS Frameworks” (AppKit on macOS; OpenGL/OpenUIKit on Windows/Linux)
f. Connect:
– Sample App → Public API Modules
– Public API Modules → Core Engine
– Core → Integration Layer → OS Frameworks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level Sample App
    SampleApp["Sample App"]:::sample

    %% OpenSwiftUI Core Modules
    subgraph "OpenSwiftUI Core"
        subgraph "Public API Modules"
            Accessibility["Accessibility"]:::api
            Animations["Animations"]:::api
            AppStructure["App Structure"]:::api
            Views["Views"]:::api
            EventHandling["Event Handling"]:::api
            DataStorage["Data & Storage"]:::api
        end
        subgraph "Core Engine"
            ViewTree["View Tree"]:::core
            ViewLayout["View Layout"]:::core
        end
    end

    %% Integration Layer
    subgraph "Integration Layer"
        FrameworkIntegration["Framework Integration"]:::integration
        Platforms["Platforms"]:::integration
    end

    %% OS Frameworks
    subgraph "OS Frameworks"
        AppKit["AppKit (macOS)"]:::os
        OpenGL["OpenGL/OpenUIKit (Win/Linux)"]:::os
    end

    %% SwiftPM & CI
    subgraph "SwiftPM & CI"
        Package["Package.swift"]:::build
        UbuntuCI["Ubuntu.yml"]:::build
        WindowsCI["Windows.yml"]:::build
    end

    %% Connections
    SampleApp -->|imports| Accessibility
    SampleApp -->|imports| Animations
    SampleApp -->|imports| AppStructure
    SampleApp -->|imports| Views
    SampleApp -->|imports| EventHandling
    SampleApp -->|imports| DataStorage

    Accessibility -->|uses| ViewTree
    Animations -->|uses| ViewTree
    AppStructure -->|uses| ViewTree
    Views -->|uses| ViewTree
    EventHandling -->|uses| ViewTree
    DataStorage -->|uses| ViewTree

    ViewTree -->|layout data| ViewLayout
    ViewLayout -->|render calls| FrameworkIntegration
    FrameworkIntegration -->|bridges| Platforms
    Platforms -->|renders| AppKit
    Platforms -->|renders| OpenGL

    Package -->|defines build| Accessibility
    Package -->|defines build| Animations
    Package -->|defines build| AppStructure
    Package -->|defines build| Views
    Package -->|defines build| EventHandling
    Package -->|defines build| DataStorage
    UbuntuCI -->|CI test| Accessibility
    WindowsCI -->|CI test| Accessibility

    %% Click events
    click SampleApp "https://github.com/helbertgs/openswiftui/blob/develop/Sources/OpenSwiftUISample/MyApp.swift"
    click Package "https://github.com/helbertgs/openswiftui/blob/develop/Package.swift"
    click UbuntuCI "https://github.com/helbertgs/openswiftui/blob/develop/.github/workflows/Ubuntu.yml"
    click WindowsCI "https://github.com/helbertgs/openswiftui/blob/develop/.github/workflows/Windows.yml"
    click Accessibility "https://github.com/helbertgs/openswiftui/tree/develop/Sources/OpenSwiftUI/Accessibility"
    click Animations "https://github.com/helbertgs/openswiftui/tree/develop/Sources/OpenSwiftUI/Animations"
    click AppStructure "https://github.com/helbertgs/openswiftui/tree/develop/Sources/OpenSwiftUI/App Structure"
    click DataStorage "https://github.com/helbertgs/openswiftui/tree/develop/Sources/OpenSwiftUI/Data and Storage"
    click EventHandling "https://github.com/helbertgs/openswiftui/tree/develop/Sources/OpenSwiftUI/Event Handling"
    click Views "https://github.com/helbertgs/openswiftui/tree/develop/Sources/OpenSwiftUI/Views"
    click ViewTree "https://github.com/helbertgs/openswiftui/tree/develop/Sources/OpenSwiftUI/View Tree"
    click ViewLayout "https://github.com/helbertgs/openswiftui/tree/develop/Sources/OpenSwiftUI/View Layout"
    click FrameworkIntegration "https://github.com/helbertgs/openswiftui/tree/develop/Sources/OpenSwiftUI/Framework Integration"
    click Platforms "https://github.com/helbertgs/openswiftui/tree/develop/Sources/OpenSwiftUI/Platforms"

    %% Styles
    classDef api fill:#cde8ff,stroke:#0288d1,color:#000
    classDef core fill:#d2f8d2,stroke:#43a047,color:#000
    classDef integration fill:#ffe0b2,stroke:#fb8c00,color:#000
    classDef build fill:#e0e0e0,stroke:#9e9e9e,color:#000
    classDef os fill:#f5f5f5,stroke:#757575,color:#000
    classDef sample fill:#bbdefb,stroke:#1976d2,color:#000
```
