# uber/needle architecture

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

- Interactive diagram: https://gitdiagram.com/uber/needle
- Repository: https://github.com/uber/needle

## Overview

##### Project type and purpose
- From the file tree and README, “Needle” is neither a front-end nor back-end web app but a Swift dependency-injection framework plus a code generator CLI.
- Two major deliverables:
– The runtime framework (`NeedleFoundation` under `Sources/NeedleFoundation`) that ships as a Carthage/SwiftPM/CocoaPods dependency.
– The code‐generation tool (`Generator` directory) which parses your Swift code, builds an internal dependency graph, and emits Swift files for compile‐time‐safe DI.
- Sample consumer apps under `Sample/…` demonstrate integration with MVC, MVVM, and pluginized architectures.

##### File structure
Top-level:
- CI / housekeeping (`.github`, `Makefile`, configs)
- Documentation (`API.md`, `GENERATOR.md`, `WHY_DI.md`, `Documents/ko_KR`)
- Generator project (`Generator/…`)
- Foundation runtime (`Sources/NeedleFoundation/…`)
- Tests for both runtime (`Tests/NeedleFoundationTests`) and framework‐specific test helpers (`Tests/NeedleFoundationTestTests`)
- Sample apps illustrating use cases (`Sample/MVC`, `Sample/Pluginized`, `Sample/SwiftUI-MVVM`)
Key architectural indicators:
- `Generator/Sources/NeedleFramework/Parsing/*` – parses Swift source into an AST.
- `Generator/Sources/NeedleFramework/Models/*` – transforms AST into an internal dependency‐graph model.
- `Generator/Sources/NeedleFramework/Generating/*` – serializes the graph into Swift code (providers, registrations).
- `Sources/NeedleFoundation/Internal` & `Pluginized/Internal` – runtime registries that hook into the generated code.

##### README for additional insights
- Calls out two steps: integrate the code generator, then write DI code using Foundation’s API.
- Highlights compile-time safety via code gen, and hierarchical component‐protocol pattern.
- Mentions external tools/libraries: SwiftSyntax / SourceKitten for parsing, Homebrew/Carthage/SwiftPM for distribution.

##### Elements
- Clear labels: e.g., “Parsing Module”, “Model Module”, “Serializer Module”, “Runtime Registry”
– Blue for generator‐time components
– Green for runtime framework
– Orange for client application
– Gray for external libraries/services
– Rectangles for modules
– Cloud/hexagon for third‐party dependencies

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Developer / CI"
        Dev["Developer / CI"]:::user
    end

    subgraph "Generator Pipeline"
        subgraph "Entry Points"
            GC["GenerateCommand"]:::generator
            PC["PrintDependencyTreeCommand"]:::generator
            Main["main.swift"]:::generator
        end
        subgraph "Parsing Module"
            ASTTask["ASTProducerTask"]:::generator
            DepParserTask["DeclarationsParserTask"]:::generator
            FileFilters["FileFilters"]:::generator
            Processors["Processors"]:::generator
            subgraph "Pluginized Parsing"
                PluginParsing["Pluginized"]:::generator
            end
        end
        subgraph "Modeling Module"
            Models["Component & DependencyGraphNode Models"]:::generator
            PluginModels["Pluginized Models"]:::generator
        end
        subgraph "Code Generation Module"
            GenTasks["DependencyProviderSerializerTask"]:::generator
            Serializers["DependencyProviderSerializer"]:::generator
            GenPlugin["Pluginized Generating"]:::generator
        end
        subgraph "External Libraries"
            SwiftSyntax["SwiftSyntax"]:::external
            SourceKitten["SourceKitten"]:::external
        end
    end

    subgraph "Compile & Runtime"
        Compiler["Xcode Build"]:::external
        RFComp["NeedleFoundation (Component & Bootstrap)"]:::runtime
        Registries["DependencyProviderRegistry"]:::runtime
        PluginReg["PluginExtensionProviderRegistry"]:::runtime
    end

    subgraph "Client Application"
        AppSrc["App Source & DI Definitions"]:::client
        GenCode["Generated Swift Code"]:::client
    end

    subgraph "Sample Apps & Tests"
        Samples["Sample Apps"]:::client
        TestsGen["Generator Tests"]:::external
        TestsRun["Runtime Tests"]:::external
    end

    Dev -->|invokes| GC
    Dev -->|invokes| PC
    Dev -->|invokes| Main

    GC --> ASTTask
    PC --> ASTTask
    ASTTask --> DepParserTask
    DepParserTask --> FileFilters
    DepParserTask --> Processors
    FileFilters --> Models
    Processors --> Models
    ASTTask --> SwiftSyntax
    ASTTask --> SourceKitten

    Models --> PluginModels
    Models --> GenTasks
    PluginModels --> GenTasks
    GenTasks --> Serializers
    Serializers --> GenPlugin
    GenPlugin --> GenCode

    GenCode --> Compiler
    AppSrc --> Compiler
    Compiler --> RFComp
    RFComp --> Registries
    RFComp --> PluginReg
    GenCode --> Registries
    AppSrc --> RFComp

    Samples -->|use| GC
    Samples -->|use| RFComp
    TestsGen --> GenTasks
    TestsRun --> Registries

    classDef generator fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef runtime fill:#d4edda,stroke:#333,stroke-width:1px
    classDef client fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef user fill:#f8d7da,stroke:#333,stroke-width:1px

    click GC "https://github.com/uber/needle/blob/master/Generator/Sources/needle/GenerateCommand.swift"
    click PC "https://github.com/uber/needle/blob/master/Generator/Sources/needle/PrintDependencyTreeCommand.swift"
    click Main "https://github.com/uber/needle/blob/master/Generator/Sources/needle/main.swift"
    click ASTTask "https://github.com/uber/needle/blob/master/Generator/Sources/NeedleFramework/Parsing/ASTProducerTask.swift"
    click FileFilters "https://github.com/uber/needle/tree/master/Generator/Sources/NeedleFramework/Parsing"
    click Processors "https://github.com/uber/needle/tree/master/Generator/Sources/NeedleFramework/Parsing"
    click PluginParsing "https://github.com/uber/needle/tree/master/Generator/Sources/NeedleFramework/Parsing/Pluginized"
    click Models "https://github.com/uber/needle/tree/master/Generator/Sources/NeedleFramework/Models"
    click PluginModels "https://github.com/uber/needle/tree/master/Generator/Sources/NeedleFramework/Models/Pluginized"
    click GenTasks "https://github.com/uber/needle/blob/master/Generator/Sources/NeedleFramework/Generating/DependencyProviderSerializerTask.swift"
    click Serializers "https://github.com/uber/needle/blob/master/Generator/Sources/NeedleFramework/Generating/DependencyProviderSerializer.swift"
    click GenPlugin "https://github.com/uber/needle/tree/master/Generator/Sources/NeedleFramework/Generating/Pluginized"
    click SwiftSyntax "https://github.com/uber/needle/blob/master/Generator/Sources/NeedleFramework/Utilities/SwiftSyntaxExtensions.swift"
    click SourceKitten "https://github.com/uber/needle/blob/master/Generator/Sources/NeedleFramework/Utilities/SourceKittenFramework/library_wrapper.swift"
    click RFComp "https://github.com/uber/needle/tree/master/Sources/NeedleFoundation"
    click Registries "https://github.com/uber/needle/blob/master/Sources/NeedleFoundation/Internal/DependencyProviderRegistry.swift"
    click PluginReg "https://github.com/uber/needle/blob/master/Sources/NeedleFoundation/Pluginized/Internal/PluginExtensionProviderRegistry.swift"
```
