# johnsundell/flow architecture

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

- Interactive diagram: https://gitdiagram.com/johnsundell/flow
- Repository: https://github.com/johnsundell/flow

## Overview

##### Project Type & Purpose
- Flow is an open-source Swift library (not a standalone app) providing a lightweight, operation-oriented programming model.
- Purpose: let client code define atomic “operations” (sync or async), then compose them into sequences, groups, queues or repeaters, simplifying complex asynchronous flows.

##### Key Architectural Components
A. Protocol Layer
- FlowOperation (core protocol for any atomic task)
- FlowOperationCollection (protocol for any multi-operation construct)
B. Core Engine
- Internal scheduler/executor driving operation lifecycle (invoke perform(), manage completion callbacks)
C. Built-In Operations
- FlowClosureOperation, FlowAsyncClosureOperation, FlowDelayOperation
D. Operation Collections
- FlowOperationSequence (serial execution)
- FlowOperationGroup (parallel execution)
- FlowOperationQueue (continual execution)
- FlowOperationRepeater (repeat logic)
E. Integration & Packaging
- Swift Package Manager (Package.swift)
- CocoaPods podspec, Carthage compatibility
- Xcode project with multi-platform schemes (iOS, macOS, tvOS, watchOS)
- Travis CI config
F. Tests
- FlowTests target under Tests/FlowTests.swift

##### Relationships & Data Flow
- Client App → imports Flow library
- Client defines custom types conforming to FlowOperation
- Client or built-in code composes operations into a collection (Sequence / Group / Queue / Repeater)
- Collection invokes each operation’s perform(completionHandler:)
- Core Engine coordinates callbacks → advances collection → signals final completion back to Client

##### Architectural Patterns & Principles
- Protocol-oriented design (FlowOperation, FlowOperationCollection)
- Composition over inheritance (operations + collections)
- Single Responsibility (each operation does one job)
- Dependency Injection (operations are initialized with dependencies)
- Platform-agnostic core (pure Swift, no UIKit/AppKit baggage)

##### Elements
- “Conforms to” from Built-In Operations and Custom Ops → FlowOperation protocol
- “Uses” from Collections → FlowOperation
- “Drives” from Core Engine → Collections/Operations
- “Imported by” from Client Code → Flow module
- Concrete classes (operations, collections) in another (e.g., rectangles)
- External/integration elements (clients, CI, package managers) in a third (e.g., clouds)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Flow Library"
        subgraph "Protocol Layer"
            FlowOperation[/"FlowOperation"/]:::protocol
            FlowOpCollection[/"FlowOperationCollection"/]:::protocol
        end
        subgraph "Core Engine"
            CoreEngine["Scheduler/Executor"]:::core
        end
        subgraph "Built-In Operations"
            FCLO["FlowClosureOperation"]:::concrete
            FACL["FlowAsyncClosureOperation"]:::concrete
            FDLO["FlowDelayOperation"]:::concrete
        end
        subgraph "Operation Collections"
            Seq["FlowOperationSequence"]:::concrete
            Grp["FlowOperationGroup"]:::concrete
            Queue["FlowOperationQueue"]:::concrete
            Rep["FlowOperationRepeater"]:::concrete
        end
    end

    ClientApp["Client App"]:::external
    CustomOp["CustomOperation"]:::concrete

    subgraph "Packaging & CI"
        SPM["Swift Package Manager"]:::integration
        Cocoa["CocoaPods"]:::integration
        Carthage["Carthage"]:::integration
        Xcode["Xcode Project"]:::integration
        Travis["Travis CI"]:::integration
        SwiftVer[".swift-version"]:::integration
        Configs["Configs"]:::integration
        TestsTarget["FlowTests"]:::integration
    end

    %% Relationships
    FCLO -->|conforms to| FlowOperation
    FACL -->|conforms to| FlowOperation
    FDLO -->|conforms to| FlowOperation
    CustomOp -->|conforms to| FlowOperation

    Seq -->|uses FlowOperation| FlowOperation
    Grp -->|uses FlowOperation| FlowOperation
    Queue -->|uses FlowOperation| FlowOperation
    Rep -->|uses FlowOperation| FlowOperation

    CoreEngine -->|drives| Seq
    CoreEngine -->|drives| Grp
    CoreEngine -->|drives| Queue
    CoreEngine -->|drives| Rep
    CoreEngine -->|drives| FlowOperation

    ClientApp -->|imports Flow module| FlowOperation
    ClientApp -->|imports Flow module| CoreEngine

    SPM -->|integrates| FlowOperation
    Cocoa -->|integrates| FlowOperation
    Carthage -->|integrates| FlowOperation
    Xcode -->|integrates| FlowOperation
    Travis -->|integrates| FlowOperation
    SwiftVer -->|integrates| FlowOperation
    Configs -->|configures| FlowOperation
    TestsTarget -->|tests| FlowOperation

    %% Click Events
    click FlowOperation "https://github.com/johnsundell/flow/blob/master/Sources/Flow.swift"
    click FlowOpCollection "https://github.com/johnsundell/flow/blob/master/Sources/Flow.swift"
    click CoreEngine "https://github.com/johnsundell/flow/blob/master/Sources/Flow.swift"
    click FCLO "https://github.com/johnsundell/flow/blob/master/Sources/Flow.swift"
    click FACL "https://github.com/johnsundell/flow/blob/master/Sources/Flow.swift"
    click FDLO "https://github.com/johnsundell/flow/blob/master/Sources/Flow.swift"
    click Seq "https://github.com/johnsundell/flow/blob/master/Sources/Flow.swift"
    click Grp "https://github.com/johnsundell/flow/blob/master/Sources/Flow.swift"
    click Queue "https://github.com/johnsundell/flow/blob/master/Sources/Flow.swift"
    click Rep "https://github.com/johnsundell/flow/blob/master/Sources/Flow.swift"
    click SPM "https://github.com/johnsundell/flow/blob/master/Package.swift"
    click Cocoa "https://github.com/johnsundell/flow/blob/master/FlowOperations.podspec"
    click Xcode "https://github.com/johnsundell/flow/blob/master/Flow.xcodeproj"
    click Travis "https://github.com/johnsundell/flow/blob/master/.travis.yml"
    click SwiftVer "https://github.com/johnsundell/flow/blob/master/.swift-version"
    click Configs "https://github.com/johnsundell/flow/blob/master/Configs/Flow.plist"
    click TestsTarget "https://github.com/johnsundell/flow/blob/master/Tests/FlowTests.swift"

    %% Styles
    classDef protocol fill:#FFD700,stroke:#333,stroke-width:1px,shape:hexagon
    classDef concrete fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef integration fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#F08080,stroke:#333,stroke-width:1px
```
