# krzysztofzablocki/inject architecture

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

- Interactive diagram: https://gitdiagram.com/krzysztofzablocki/inject
- Repository: https://github.com/krzysztofzablocki/inject

## Overview

##### Project Type and Purpose
- This is an open‑source Swift package (library) designed to add “hot‑reload” capabilities to iOS/macOS apps (UIKit, AppKit, SwiftUI) by wrapping and simplifying the use of the external InjectionIII tool.
- It’s not a full‑stack application but rather a developer‑workflow helper that plugs into existing projects via SwiftPM or CocoaPods and runtime linker flags.

##### File Structure Analysis
- Top‑level artifacts:
- Package.swift / InjectHotReload.podspec → SPM & CocoaPods integration points
- .swiftpm / Xcode workspace files → Build integration scaffolding
- Sources/Inject → Core library module
- Under Sources/Inject:
- InjectConfiguration.swift → runtime settings (e.g., animation)
- Integrations/KitFrameworks.swift → UIKit/AppKit support
- Integrations/Hosts.swift → ViewControllerHost & ViewHost abstractions for state cleanup
- Integrations/SwiftUI.swift → SwiftUI modifiers (`.enableInjection()`, `@ObserveInjection`)

##### README Insights
- Describes how Inject is a “thin wrapper” around InjectionIII, adding no‑op behavior in production builds.
- Provides step‑by‑step integration instructions for SwiftPM, CocoaPods, Xcode build flags, and per‑developer setup.
- Demonstrates two major integration patterns: SwiftUI and imperative UI (UIKit/AppKit) via host wrappers and injection hooks.
- Emphasizes that the only external service/tool is the InjectionIII macOS app, which compiles & pushes code into the running process over a debug IPC channel.

##### Main Components
a. Developer’s iOS/macOS App
- Your app target with code that does `import Inject`, adds `@ObserveInjection`, calls `.enableInjection()` or wraps views/controllers with `Inject.ViewHost`/`ViewControllerHost`.
b. Inject Library (client side)
- InjectConfiguration
- Hosts (ViewHost, ViewControllerHost)
- Framework integrations (UIKit/AppKit)
- SwiftUI extensions
c. Build System
- Swift Package Manager or CocoaPods (package resolution, linking)
- Xcode build flags (`-Xlinker -interposable`, `-weak_framework SwiftUI` for iOS 12)
d. External Tool
- InjectionIII macOS app (monitors file changes, recompiles code delta, communicates over IPC/dlopen)
e. Runtime Flow
- InjectionIII → dynamic code injection into the running app → Inject’s runtime hooks trigger view/controller reload.

##### Relationships & Data Flows
- At Build Time:
- App target links against Inject library via SPM/CocoaPods.
- Compiler and linker flags ensure symbols are interposable.
- At Runtime:
1. InjectionIII watches source files & recompiles deltas.
2. It injects compiled code into the running app via debugger hooks/dlopen.
3. Inject library intercepts that event (via `@autoclosure` reload hooks).
4. Hosts unwrap and reinstantiate views/controllers, or SwiftUI view bodies recompute with `.enableInjection()`.

##### Architectural Patterns & Principles
- Thin wrapper/adaptor pattern: Inject adapts the InjectionIII engine into a developer‑friendly API.
- Host/Container pattern: separates mutable host layers from immutable view/controller logic.
- No‑op in production: uses conditional compilation and interposable symbols stripped by LLVM.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Setup Layer
    subgraph "Build Setup"
        direction TB
        SPM["Swift Package Manager"]:::build
        CocoaPods["CocoaPods"]:::build
        BuildFlags["Xcode Linker Flags"]:::build
        WorkspaceFile1["Xcode Workspace"]:::build
        WorkspaceFile2["Workspace Data"]:::build
    end

    %% Inject Library Layer
    subgraph "Inject Library" 
        direction TB
        InjectModule["Core Module\nSources/Inject"]:::library
        Config["InjectConfiguration.swift"]:::library
        KitFrameworks["KitFrameworks.swift"]:::library
        Hosts["Hosts.swift"]:::library
        SwiftUI["SwiftUI.swift"]:::library
    end

    %% App Target Layer
    subgraph "App Target"
        direction TB
        AppProcess["App Process\n(import Inject)"]:::app
        UIComponents["UI Components\n(Views/Controllers)"]:::app
    end

    %% External Tool Layer
    subgraph "External Tool"
        direction TB
        InjectionIII["InjectionIII App"]:::external
    end

    %% Build-Time Relationships
    SPM -->|"SPM fetch & link"| AppProcess
    CocoaPods -->|"Pod install & link"| AppProcess
    BuildFlags -->|"-Xlinker -interposable\n-weak_framework SwiftUI"| AppProcess
    WorkspaceFile1 -->|"Xcode integration"| AppProcess
    WorkspaceFile2 -->|"Workspace data load"| AppProcess

    %% Library Linking
    AppProcess -->|"links against"| InjectModule
    InjectModule --> Config
    InjectModule --> KitFrameworks
    InjectModule --> Hosts
    InjectModule --> SwiftUI

    %% Runtime Flow
    IDE["IDE (Xcode)"]:::external -->|"trigger build/watch"| InjectionIII
    InjectionIII -->|"IPC / dlopen injection"| AppProcess
    AppProcess -->|"@autoclosure reload hook"| Hosts
    AppProcess -->|"SwiftUI modifier hook"| SwiftUI
    Hosts -->|"reinstantiate Controllers"| UIComponents
    SwiftUI -->|"recompute View bodies"| UIComponents

    %% Click Events
    click SPM "https://github.com/krzysztofzablocki/inject/blob/main/Package.swift"
    click CocoaPods "https://github.com/krzysztofzablocki/inject/blob/main/InjectHotReload.podspec"
    click WorkspaceFile1 "https://github.com/krzysztofzablocki/inject/blob/main/.swiftpm/xcode/package.xcworkspace"
    click WorkspaceFile2 "https://github.com/krzysztofzablocki/inject/blob/main/.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata"
    click InjectModule "https://github.com/krzysztofzablocki/inject/tree/main/Sources/Inject"
    click Config "https://github.com/krzysztofzablocki/inject/blob/main/Sources/Inject/InjectConfiguration.swift"
    click KitFrameworks "https://github.com/krzysztofzablocki/inject/blob/main/Sources/Inject/Integrations/KitFrameworks.swift"
    click Hosts "https://github.com/krzysztofzablocki/inject/blob/main/Sources/Inject/Integrations/Hosts.swift"
    click SwiftUI "https://github.com/krzysztofzablocki/inject/blob/main/Sources/Inject/Integrations/SwiftUI.swift"
    click README "https://github.com/krzysztofzablocki/inject/blob/main/README.md"

    %% Styles
    classDef build fill:#D0E8FF,stroke:#0366D6,color:#0366D6,stroke-width:1px;
    classDef library fill:#DFFFD6,stroke:#2E8B57,color:#2E8B57,stroke-width:1px;
    classDef app fill:#F0F0F0,stroke:#666666,color:#333333,stroke-width:1px;
    classDef external fill:#FFE4B5,stroke:#FF8C00,color:#FF8C00,stroke-width:1px;
```
