# hlung/swiftflow architecture

> Architecture diagram of the GitHub repository hlung/swiftflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hlung/swiftflow
- Repository: https://github.com/hlung/swiftflow

## Overview

##### What this project is (type + purpose)

So your “system” is not a distributed system; it’s a **library architecture** with:
- **Public API layer** (models + `GraphView`)
- **Layout engine** (constraints for node placement)
- **UIKit view composition** (`NodeView`, `Label`, `GraphView`)
- **Tests** (basic package tests)

##### How the repository structure maps to architecture
From the file tree:

##### Package / build / CI
- `Package.swift` — Swift Package Manager manifest; define module(s), platforms, dependencies.
- `.github/workflows/swift.yml` — CI pipeline (build/test).

##### Library code
`Sources/SwiftFlow/`
- `Models/`
- Layout/drawing supporting structs: `ArrowDrawingPlan.swift`, `EdgeOffsets.swift`
- Enums: `Direction`, `NodeShape`, `GraphDrawError`
- `Views/`
- `NodeView.swift`, `Label.swift` — UIKit subviews for nodes/labels
- `UIKit+Direction.swift` — direction helpers, geometry utilities

##### Tests
- `Tests/SwiftFlowTests/SwiftFlowTests.swift` — unit tests (likely model/layout sanity).

This strongly suggests a **Model → View rendering** architecture with a small “layout engine” embedded inside `GraphView`/supporting model structs.

The README states:
- Users define flows via `graph.addFlow([GraphElement])`
- Layout is done with **Auto Layout** for nodes

This implies two distinct phases:

##### Consumer / Client App
- Example usage code calls into SwiftFlow.

##### SwiftFlow Public API (Models)
- `Graph`
- `GraphElement` protocol
- `Node`, `NodeShortcut`
- `NodeConfig`, `ArrowConfig`
- Enums: `Direction`, `NodeShape`
- Errors: `GraphDrawError`

##### Graph Construction / Resolution
- Flow arrays ingestion: `Graph.addFlow([GraphElement])`
- ID registry / reference resolution: `NodeShortcut(id:)` → existing `Node`

##### View Layer (UIKit)
- `GraphView` (container view, orchestrator)

##### Output
- Rendered `UIView` hierarchy on screen (Simulator/iPad simulator per README)

- **SwiftUI Preview integration** (README mentions `UIViewRepresentable` wrapper; not in repo, but note as external usage pattern).

##### Graph stores
- Flow sequences
- Node registry by `id`
##### GraphView
- builds `NodeView` + `Label` for each `Node`
- applies **Auto Layout constraints** (Layout Engine)
##### GraphView reads node frames → creates ArrowDrawingPlan

- “Before layout: constraints”

##### Architectural patterns / principles to highlight

- **Declarative DSL-ish input**: flows as `[GraphElement]`
- **Two-phase rendering pipeline**:
- Phase 1: Auto Layout for nodes
- **Reference resolution**: `NodeShortcut` uses `id` to avoid node duplication
- **Separation of concerns**:
- Views/paths describe *how* to render

As small tags on components:
- **Swift Package Manager** (Package.swift)
- **UIKit** (`UIView`, `NSLayoutConstraint`)
- **CoreGraphics/UIBezierPath**
- **SwiftUI Preview** (external wrapper usage, optional)
- **CI** (GitHub Actions)

Of the following:

- **Clear labels**: use the *actual type/file names* where possible (`GraphView`, `Graph`, `NodeView`, `ArrowDrawingPlan`).
- External = gray (Client App, UIKit runtime, SwiftUI wrapper)

##### “Don’t overthink it”: split into as many components as possible (but still coherent)

- Under **Views**: `GraphView`, `NodeView`, `Label`

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Top-level: Package + CI
  %% =========================
  subgraph "Build & CI"
    direction TB
    Pkg["Swift Package Manifest\n(SwiftPM)"]:::build
    CI["GitHub Actions CI\n(build + test)"]:::build
  end

  %% =========================
  %% External Consumers
  %% =========================
  subgraph "External"
    direction TB
    Client["Client iOS App\n(UIKit/SwiftUI host)"]:::external
    SwiftUIWrap["SwiftUI Preview Wrapper\n(UIViewRepresentable)\n(optional usage)"]:::external
    UIKitRuntime["UIKit Runtime\n(Auto Layout + Rendering)"]:::external
    CGRuntime["CoreGraphics / UIBezierPath\n(Drawing)"]:::external
  end

  %% =========================
  %% SwiftFlow Library
  %% =========================
  subgraph "SwiftFlow Library (Swift Package)"
    direction TB

    %% -------------------------
    %% Public API Models
    %% -------------------------
    subgraph "Public API: Models (Declarative DSL-ish Input)"
      direction TB
      Graph["Graph\n(addFlow, registry, flows)"]:::model
      Protocols["GraphElement Protocols"]:::model
      Node["Node"]:::model
      Arrow["Arrow"]:::model
      ArrowLoop["ArrowLoopBack\n(concept in README)"]:::model
      Configs["NodeConfig / ArrowConfig"]:::model
      DirectionEnum["Direction"]:::model
      NodeShapeEnum["NodeShape"]:::model
      DrawError["GraphDrawError"]:::model
    end

    %% -------------------------
    %% View Composition + Layout
    %% -------------------------
    subgraph "Phase 1: Node View Composition + Auto Layout"
      direction TB
      GraphView["GraphView\n(draw(graph) orchestrator)"]:::view
      NodeView["NodeView"]:::view
      LabelView["Label"]:::view
      LayoutEngine["Layout Engine\n(NSLayoutConstraint builder)\n(uses layoutMargins)"]:::layout
      LayoutPass["UIKit Layout Pass\n(resolves constraints -> frames)"]:::layout
    end

    %% -------------------------
    %% Arrow Planning + Rendering
    %% -------------------------
    subgraph "Phase 2: Arrow Planning + Bezier Rendering (Post-layout)"
      direction TB
      Plan["ArrowDrawingPlan\n(computed from node frames)"]:::drawing
      Offsets["EdgeOffsets\n(routing offsets)"]:::drawing
      UIKitDir["UIKit+Direction\n(geometry utilities)"]:::drawing
      BezierArrow["UIBezierPath+Arrow\n(arrow primitives)"]:::drawing
      BezierDiamond["UIBazierPath+Diamond\n(shape primitives)"]:::drawing
      ArrowRender["Arrow Renderer\n(UIBezierPath -> CoreGraphics)"]:::drawing
    end

    Output["Rendered Flowchart\n(UIView hierarchy + drawn arrows)"]:::output
  end

  %% =========================
  %% Control Flow (solid)
  %% =========================
  Client -->|"defines [GraphElement]"| Protocols
  Client -->|"Graph.addFlow([GraphElement])"| Graph
  Protocols -->|"implemented by"| Node
  Protocols -->|"implemented by"| Arrow
  Protocols -->|"implemented by"| ArrowLoop

  Client -->|"GraphView.draw(graph)"| GraphView
  GraphView -->|"reads"| Graph
  GraphView -->|"creates"| NodeView
  GraphView -->|"creates"| LabelView
  GraphView -->|"builds constraints"| LayoutEngine
  LayoutEngine -->|"activates NSLayoutConstraint"| LayoutPass
  LayoutPass -->|"produces final frames"| GraphView

  GraphView -->|"creates"| Plan
  Plan -->|"uses"| Offsets
  Plan -->|"uses"| UIKitDir
  ArrowRender -->|"uses"| BezierArrow
  ArrowRender -->|"uses"| BezierDiamond
  ArrowRender -->|"draws into GraphView"| Output

  %% =========================
  %% Data Dependencies (dashed)
  %% =========================
  Node -.->|"configures"| Configs
  Arrow -.->|"configures"| Configs
  Arrow -.->|"uses"| DirectionEnum
  Node -.->|"uses"| NodeShapeEnum
  Graph -.->|"throws"| DrawError

  LayoutPass -.->|"node frames"| Plan
  UIKitRuntime -.->|"executes layout & view rendering"| LayoutPass
  CGRuntime -.->|"strokes/fills paths"| ArrowRender

  SwiftUIWrap -.->|"hosts"| GraphView
  Output -->|"displayed in"| Client

  %% =========================
  %% Build/Test Relations
  %% =========================
  Pkg -->|"builds module"| Graph
  Pkg -->|"builds module"| GraphView
  CI -->|"runs tests"| Tests
  CI -->|"uses"| Pkg

  subgraph "Tests"
    direction TB
    Tests["SwiftFlowTests\n(XCTest)"]:::test
    LinuxMain["LinuxMain.swift"]:::test
    XCTestMan["XCTestManifests.swift"]:::test
  end

  Tests -->|"imports"| Graph
  Tests -->|"imports"| GraphView

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click Pkg "https://github.com/hlung/swiftflow/blob/master/Package.swift"
  click CI "https://github.com/hlung/swiftflow/blob/master/.github/workflows/swift.yml"

  click Graph "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Models/Graph.swift"
  click Node "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Models/Node.swift"
  click Arrow "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Models/Arrow.swift"
  click Protocols "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Models/Protocols.swift"
  click Configs "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Models/Configs.swift"
  click DirectionEnum "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Models/Enums/Direction.swift"
  click NodeShapeEnum "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Models/Enums/NodeShape.swift"
  click DrawError "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Models/Enums/GraphDrawError.swift"

  click GraphView "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Views/GraphView.swift"
  click NodeView "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Views/NodeView.swift"
  click LabelView "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Views/Label.swift"

  click Plan "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Models/ArrowDrawingPlan.swift"
  click Offsets "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Models/EdgeOffsets.swift"

  click BezierArrow "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Views/UIBezierPath+Arrow.swift"
  click BezierDiamond "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Views/UIBazierPath+Diamond.swift"
  click UIKitDir "https://github.com/hlung/swiftflow/blob/master/Sources/SwiftFlow/Views/UIKit+Direction.swift"

  click Tests "https://github.com/hlung/swiftflow/blob/master/Tests/SwiftFlowTests/SwiftFlowTests.swift"
  click LinuxMain "https://github.com/hlung/swiftflow/blob/master/Tests/LinuxMain.swift"
  click XCTestMan "https://github.com/hlung/swiftflow/blob/master/Tests/SwiftFlowTests/XCTestManifests.swift"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ECEFF4,stroke:#4C566A,color:#2E3440,stroke-width:1px
  classDef build fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20,stroke-width:1px
  classDef model fill:#E3F2FD,stroke:#1565C0,color:#0D47A1,stroke-width:1px
  classDef view fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C,stroke-width:1px
  classDef layout fill:#FFF8E1,stroke:#FF8F00,color:#E65100,stroke-width:1px
  classDef drawing fill:#E0F7FA,stroke:#00838F,color:#006064,stroke-width:1px
  classDef output fill:#FFEBEE,stroke:#C62828,color:#B71C1C,stroke-width:1px
  classDef test fill:#F1F8E9,stroke:#558B2F,color:#33691E,stroke-width:1px
```
