# sdidla/hatch architecture

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

- Interactive diagram: https://gitdiagram.com/sdidla/hatch
- Repository: https://github.com/sdidla/hatch

## Overview

##### Main Components
- Core Library (Sources/Hatch): This is the heart of the package, which includes classes and structs such as SymbolParser, Symbol, Symbol+Flattened, Scope, and StringBuilder. These components represent the parsing logic, symbol representation, tree building, and other internal utilities.
- Example Usage (Sources/HatchExample): A sample application demonstrating how to use the Hatch library. This component should be shown as a client that imports the core parser and invokes the parsing functionality over a given Swift source code.
- Tests (Tests/HatchTests): Unit tests validating the functionality of the core components (for instance, the tests in SymbolVisitorTests.swift). This identifies a quality assurance layer.
- Configuration and CI/CD: There are CI configuration files in .circleci and .github, which indicate that there is an integrated pipeline for running tests and maintaining code quality. Although not part of the runtime architecture, they play an important role in the development and deployment lifecycle.
- Package and Build Configurations: Files like Package.swift, Package.resolved, and other SwiftPM configuration indicate how the project is built and managed.

##### Relationships and Interactions
- Input Flow: Show how Swift source code is provided (or read) by the client application (HatchExample), which then passes the code to the SymbolParser.
- Parsing Flow: Within the Core Library, illustrate that the SymbolParser uses SwiftSyntax to “walk” the Swift code and build a hierarchical structure of symbols. Represent how symbols (structs, enums, etc.) are constructed and organized (possibly indicating parent-child relationships).
- Output: The parser returns a structured list (likely as a tree of node objects) that could be dumped or further utilized by a user.

##### Architectural Patterns and Design Principles
- Modular Design: The project clearly separates concerns (parsing logic, example usage, and testing).
- Clean API Integration: As demonstrated in the README, the project is intended for Swift Package Manager consumption. Represent an “API Boundary” between the user’s code and the library internals.

##### Final Advice to the Principal Software Engineer
- Drill down into the Core Library to illustrate how the parsing logic works (input, processing, output).
- External dependencies, e.g., SwiftSyntax integration, and note how it is central to parsing operations.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input & Client Layer
    A["Swift Source Input"]:::runtime
    B["HatchExample (Example Usage)"]:::runtime
    A -->|"provides_source"| B

    %% Core Library: Hatch
    subgraph "Core Library: Hatch"
        C1["SymbolParser"]:::runtime
        C2["Symbol"]:::runtime
        C3["Symbol+Flattened"]:::runtime
        C4["Scope"]:::runtime
        C5["StringBuilder"]:::runtime
        C1 -->|"builds"| C2
        C2 -->|"flattens_to"| C3
        C1 -->|"uses"| C4
        C1 -->|"utilizes"| C5
    end
    B -->|"invokes"| C1

    %% External Dependency
    D["SwiftSyntax (External)"]:::external
    D -->|"parses_code"| C1

    %% Testing Layer
    E["Unit Tests (HatchTests)"]:::test
    E -->|"validates"| C1

    %% CI/CD and Configuration
    subgraph "CI/CD & Configurations"
        F["CircleCI"]:::ci
        G["GitHub Actions"]:::ci
        H["Package.swift"]:::config
        I["Package.resolved"]:::config
        F -->|"runs_tests"| E
        G -->|"runs_tests"| E
        H --- I
    end

    %% Click Events
    click C1 "https://github.com/sdidla/hatch/blob/main/Sources/Hatch/SymbolParser.swift"
    click C2 "https://github.com/sdidla/hatch/blob/main/Sources/Hatch/Symbol.swift"
    click C3 "https://github.com/sdidla/hatch/blob/main/Sources/Hatch/Symbol+Flattened.swift"
    click C4 "https://github.com/sdidla/hatch/blob/main/Sources/Hatch/Scope.swift"
    click C5 "https://github.com/sdidla/hatch/blob/main/Sources/Hatch/StringBuilder.swift"
    click B "https://github.com/sdidla/hatch/blob/main/Sources/HatchExample/HatchExample.swift"
    click E "https://github.com/sdidla/hatch/blob/main/Tests/HatchTests/SymbolVisitorTests.swift"
    click F "https://github.com/sdidla/hatch/blob/main/.circleci/disabled.config.yml"
    click G "https://github.com/sdidla/hatch/blob/main/.github/workflows/unit-tests.yml"
    click H "https://github.com/sdidla/hatch/blob/main/Package.swift"
    click I "https://github.com/sdidla/hatch/blob/main/Package.resolved"

    %% Styles
    classDef runtime fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef test fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef ci fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef config fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px,stroke-dasharray:5 5;
    
    class A,B,C1,C2,C3,C4,C5 runtime;
    class D external;
    class E test;
    class F,G ci;
    class H,I config;
```
