# yonaskolb/xcodegen architecture

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

- Interactive diagram: https://gitdiagram.com/yonaskolb/xcodegen
- Repository: https://github.com/yonaskolb/xcodegen

## Overview

##### Project Type and Purpose
– XcodeGen is an open-source, full-featured command-line tool (CLI) written in Swift.
– Its purpose is to read a project specification (YAML/JSON) and generate an Xcode project (.xcodeproj), keeping folder structure, settings, schemes, targets, and dependencies in sync.

##### High-Level File Structure Analysis
Top-level directories:
- Sources – contains product modules:
– ProjectSpec: models, decoding/validation of spec file
– XcodeGenCLI: command-line interface and argument parsing
– XcodeGenCore: core utilities (file paths, globbing, atomic writes, MD5)
– XcodeGenKit: generation engine (generators for PBXProj, schemes, Info.plist, settings, templating)
– TestSupport: shared helpers for tests
– XcodeGen/main.swift: entry point
- SettingPresets – built-in YAML presets for platforms, products, settings groups
- Assets – logo & gifs used in README/demo
- Docs – documentation (ProjectSpec, Usage, Examples, FAQ)
- Tests – unit, fixture, performance tests covering each module
- .scripts & Makefile – CI, install, fixture generation

##### Architectural Patterns & Relationships
– Modular layers:
CLI Layer (XcodeGenCLI)
→ Specification Layer (ProjectSpec)
→ Core Utilities (XcodeGenCore)
→ Generation Engine (XcodeGenKit)
→ File System Output (FileWriter, cache)
– Pipeline pattern:
User invokes `xcodegen` → CLI parses arguments → SpecLoader loads & decodes spec → Validation → Schematic generation by multiple generators → FileWriter writes .xcodeproj

##### Key Components
a. User Interface:
- `xcodegen` CLI (XcodeGenCLI module)
b. Data Input:
- Project Spec (project.yml + included files, YAML/JSON)
c. Core Services:
- Spec Loader & Validator (ProjectSpec)
- Utilities (XcodeGenCore)
- Preset Loader (SettingPresets directory)
d. Generation Engine (XcodeGenKit):
- ProjectGenerator
- PBXProjGenerator
- SchemeGenerator
- InfoPlistGenerator
- CarthageDependencyResolver
- FileWriter
e. Output:
- Generated Xcode project (.xcodeproj)
- Cache file (if `--use-cache`)

##### Data Flow & Dependencies
– Spec Loader → Core Utilities (for file system traversal, glob)
– Spec Loader → Preset Loader (merging built-in settings)
– Validated Spec → Generation Engine → each generator subcomponent
– Generators → FileWriter → Disk (writes project files)

##### Architectural Patterns & Design Principles
– Single Responsibility: each module handles one concern (CLI, spec parsing, FS utilities, generation)
– Layered Architecture: clear separation between interface, domain model, utilities, and output
– Pipeline/Strategy in Generation Engine: plug-in style generators for each part of the Xcode project
– Resource-driven: SettingPresets directory provides external YAML configurations loaded at runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User"]:::user
    User -->|invokes| CLI_Main

    %% CLI Layer
    CLI_Main["main.swift"]:::cli
    CLI_Module["XcodeGenCLI"]:::cli
    CLI_Main -->|calls CLI module| CLI_Module

    %% Specification Layer
    subgraph "Specification Layer"
        SpecLoader["SpecLoader"]:::domain
        SpecValidation["SpecValidation"]:::domain
    end

    CLI_Module -->|parse args| SpecLoader
    SpecLoader -->|validate spec| SpecValidation

    %% Core Utilities Layer
    subgraph "Core Utilities"
        Core["XcodeGenCore"]:::core
    end

    SpecLoader -->|file traversal| Core

    %% Preset Loader
    Presets["SettingPresets"]:::external
    SpecLoader -->|merge presets| Presets

    %% Generation Engine
    subgraph "Generation Engine"
        PG["ProjectGenerator"]:::kit
        PBX["PBXProjGenerator"]:::kit
        SG["SchemeGenerator"]:::kit
        IP["InfoPlistGenerator"]:::kit
        CDR["CarthageDependencyResolver"]:::kit
        FW["FileWriter"]:::kit
        PresetsKit["SettingPresets (runtime)"]:::kit
    end

    SpecValidation -->|produce spec model| PG
    PG -->|generate PBXProj| PBX
    PG -->|generate schemes| SG
    PG -->|generate Info.plist| IP
    PG -->|resolve Carthage| CDR

    PBX -->|generate| FW
    SG -->|generate| FW
    IP -->|generate| FW
    CDR -->|generate| FW
    PresetsKit -->|provide runtime presets| PG

    %% File Writing & Output
    Cache(("Cache File")):::cache
    Disk(("Generated .xcodeproj")):::output

    FW -->|write files| Disk
    FW -->|read/write cache| Cache

    %% Click Events
    click CLI_Main "https://github.com/yonaskolb/xcodegen/blob/master/Sources/XcodeGen/main.swift"
    click CLI_Module "https://github.com/yonaskolb/xcodegen/tree/master/Sources/XcodeGenCLI"
    click SpecLoader "https://github.com/yonaskolb/xcodegen/blob/master/Sources/ProjectSpec/SpecLoader.swift"
    click SpecValidation "https://github.com/yonaskolb/xcodegen/blob/master/Sources/ProjectSpec/SpecValidation.swift"
    click Core "https://github.com/yonaskolb/xcodegen/tree/master/Sources/XcodeGenCore"
    click Presets "https://github.com/yonaskolb/xcodegen/tree/master/SettingPresets"
    click PG "https://github.com/yonaskolb/xcodegen/blob/master/Sources/XcodeGenKit/ProjectGenerator.swift"
    click PBX "https://github.com/yonaskolb/xcodegen/blob/master/Sources/XcodeGenKit/PBXProjGenerator.swift"
    click SG "https://github.com/yonaskolb/xcodegen/blob/master/Sources/XcodeGenKit/SchemeGenerator.swift"
    click IP "https://github.com/yonaskolb/xcodegen/blob/master/Sources/XcodeGenKit/InfoPlistGenerator.swift"
    click CDR "https://github.com/yonaskolb/xcodegen/blob/master/Sources/XcodeGenKit/CarthageDependencyResolver.swift"
    click FW "https://github.com/yonaskolb/xcodegen/blob/master/Sources/XcodeGenKit/FileWriter.swift"
    click PresetsKit "https://github.com/yonaskolb/xcodegen/tree/master/Sources/XcodeGenKit/SettingPresets"
    click Cache "https://github.com/yonaskolb/xcodegen/blob/master/Sources/ProjectSpec/CacheFile.swift"
    click Disk "https://github.com/yonaskolb/xcodegen/blob/master/."

    %% Styles
    classDef user fill:#e0ffe0,stroke:#006600,color:#006600;
    classDef cli fill:#e0ffcc,stroke:#339900,color:#333333;
    classDef domain fill:#cce5ff,stroke:#0047b3,color:#003366;
    classDef core fill:#ffe0b3,stroke:#cc7a00,color:#663d00;
    classDef kit fill:#e5ccff,stroke:#6600cc,color:#330066;
    classDef external fill:#f2f2f2,stroke:#999999,color:#333333;
    classDef output fill:#dddddd,stroke:#555555,color:#000000,stroke-dasharray: 5 5;
    classDef cache fill:#ffebcc,stroke:#ff9900,color:#663300;
```
