# akaduality/build-graph-for-xcode architecture

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

- Interactive diagram: https://gitdiagram.com/akaduality/build-graph-for-xcode
- Repository: https://github.com/akaduality/build-graph-for-xcode

## Overview

##### Project Type & Purpose
- This is a modular, multi‐package macOS desktop application written in Swift.
- Purpose: visual analysis of Xcode build times by parsing build logs (`.xcactivitylog`) and the Xcode target-graph, then rendering a module‐dependency graph with interactive filters.

##### High-Level Modules (components)
- App (App/App)
- macOS application entry point (AppDelegate, MainWindow, Menu, Storyboards)
- Glue between the UI package, the Domain package, and peripheral services (e.g. Firebase in Release target)
- UI (UI/Sources)
- Projects panel (left pane): project discovery & selection
- Details panel (center pane): graph drawing, uses Domain layers for graph model → renders via AppKit/Storyboard
- Filters panel (right pane): filter configuration for build steps, modules, time ranges
- UI implements an MVP/MVC‐style pattern (Presenters, StateViewControllers)
- Domain (Domain/Sources)
- BuildParser: reads and parses `.xcactivitylog` files into domain events, durations, concurrency layers
- GraphParser: reads Xcode’s `target-graph.txt` to extract module dependencies
- Snapshot: sample build snapshots for testing/demo
- Domain is a pure Swift library with no UI, organized into subpackages: Parsing, Layers, Domain models, Storage
- XCLogParser (XCLogParser/Sources)
- Low‐level log‐parsing toolkit (lexer, parser, reporters) leveraged by Domain.BuildParser
- Independent Swift package, optimized to avoid String allocations

##### External Systems & Data Sources
- Xcode (external build process) → produces DerivedData folder containing `.xcactivitylog` and target-graph files
- Firebase (used in Release target only for analytics/crash reporting)

##### Dependencies & Data Flows
- User launches App → AppDelegate initializes UI modules
- UI.ProjectsPresenter invokes Domain.ProjectsFinder to enumerate projects in DerivedData
- Upon project selection:
- Domain.GraphParser parses the target‐graph file → returns module dependency graph
- Domain.BuildParser uses XCLogParser under the hood to parse `.xcactivitylog` → emits build events and timing
- Domain.Layers build layered representations (timeline, vertical lines, modules layers)
- UI.DetailsController takes the domain layers → draws the graph in the center pane
- UI.FiltersController manipulates Domain.FilterSettings → re‐asks Domain to re‐filter layers
- App coordinates reading/writing settings (e.g. image export, snapshot save services)

##### Key Architectural Patterns & Principles
- Layered Architecture: UI → Domain → XCLogParser → File System
- Separation of Concerns:
- UI package is strictly responsible for presentation and user flow
- Domain package is purely business logic & parsing, no UI dependencies
- XCLogParser is an independent utility library (lexer & parser)
- MVP/MVC in UI with Presenters and StateViewControllers for each screen/state
- Swift Package Manager organizes each module as its own package with Package.swift

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        direction TB
        XcodeBuild["Xcode Build"]:::external
        Firebase["Firebase (Release)"]:::external
    end

    %% XCLogParser Package
    subgraph "XCLogParser" 
        direction TB
        XCLogParserPkg["XCLogParser"]:::parser
    end

    %% Domain Package
    subgraph "Domain" 
        direction TB
        BuildParser["BuildParser"]:::domain
        GraphParser["GraphParser"]:::domain
        SnapshotDom["Snapshot"]:::domain
    end

    %% UI Package
    subgraph "UI" 
        direction TB
        subgraph "Projects Panel"
            direction TB
            UIProjects["ProjectsPresenter"]:::ui
            UIProjectsVC["ProjectsStateViewController"]:::ui
        end
        subgraph "Details Panel"
            direction TB
            DetailsVC["DetailViewController"]:::ui
            HUDView["HUDView"]:::ui
            DetailsPresenter["DetailsStatePresenter"]:::ui
        end
        subgraph "Filters Panel"
            direction TB
            FiltersVC["SettingsPopoverViewController"]:::ui
            FilterDesc["DetailStepTypeDescription"]:::ui
        end
    end

    %% App Package
    subgraph "App" 
        direction TB
        AppDelegate["CommonAppDelegate"]:::app
        MainWindow["MainWindow"]:::app
        AppMenu["AppMenu"]:::app
        Storyboard["Main.storyboard"]:::app
    end

    %% Connections
    XcodeBuild -->|".xcactivitylog → parsed events"| BuildParser
    XcodeBuild -->|"target-graph.txt → dependency graph"| GraphParser
    BuildParser -->|"layers data"| SnapshotDom
    BuildParser -->|"layered models"| DetailsVC
    GraphParser -->|"dependency graph"| DetailsVC
    UIProjects -->|"find projects"| BuildParser
    UIProjects -->|"find projects"| GraphParser
    FiltersVC -->|"filter settings"| BuildParser
    FiltersVC -->|"filter settings"| SnapshotDom
    AppDelegate -->|init| UIProjects
    AppDelegate -->|init| DetailsVC
    AppDelegate -->|init| FiltersVC
    AppDelegate -->|init| BuildParser
    AppDelegate -->|init| GraphParser
    AppDelegate -->|init| XCLogParserPkg
    AppDelegate -->|init| Firebase

    %% Click Events
    click XCLogParserPkg "https://github.com/akaduality/build-graph-for-xcode/tree/main/XCLogParser/Sources/XCLogParser"
    click BuildParser "https://github.com/akaduality/build-graph-for-xcode/tree/main/Domain/Sources/BuildParser"
    click GraphParser "https://github.com/akaduality/build-graph-for-xcode/blob/main/Domain/Sources/GraphParser/DependencyParser.swift"
    click SnapshotDom "https://github.com/akaduality/build-graph-for-xcode/blob/main/Domain/Sources/BuildParser/Snapshot/XcodeBuildSnapshot.swift"
    click UIProjects "https://github.com/akaduality/build-graph-for-xcode/blob/main/UI/Sources/Projects/ProjectsPresenter.swift"
    click UIProjectsVC "https://github.com/akaduality/build-graph-for-xcode/blob/main/UI/Sources/Projects/ProjectsStateViewController.swift"
    click DetailsVC "https://github.com/akaduality/build-graph-for-xcode/blob/main/UI/Sources/Details/Details/DetaliViewController.swift"
    click HUDView "https://github.com/akaduality/build-graph-for-xcode/blob/main/UI/Sources/Details/Details/HUDView.swift"
    click DetailsPresenter "https://github.com/akaduality/build-graph-for-xcode/blob/main/UI/Sources/Details/States/DetailsStatePresenter.swift"
    click FiltersVC "https://github.com/akaduality/build-graph-for-xcode/blob/main/UI/Sources/Filters/SettingsPopoverViewController.swift"
    click FilterDesc "https://github.com/akaduality/build-graph-for-xcode/blob/main/UI/Sources/Filters/DetailStepTypeDescription.swift"
    click AppDelegate "https://github.com/akaduality/build-graph-for-xcode/blob/main/App/App/Sources/App/CommonAppDelegate.swift"
    click MainWindow "https://github.com/akaduality/build-graph-for-xcode/blob/main/App/App/Sources/App/MainWindow.swift"
    click AppMenu "https://github.com/akaduality/build-graph-for-xcode/blob/main/App/App/Sources/App/Menu/AppMenu.swift"
    click Storyboard "https://github.com/akaduality/build-graph-for-xcode/blob/main/App/App/Sources/App/Base.lproj/Main.storyboard"

    %% Styles
    classDef external fill:#f8f9fa,stroke:#6c757d,stroke-dasharray:5,stroke-width:1px;
    classDef parser fill:#e2e3e5,stroke:#6c757d;
    classDef domain fill:#fff3cd,stroke:#856404;
    classDef ui fill:#d4edda,stroke:#155724;
    classDef app fill:#cce5ff,stroke:#004085;
```
