# inditextech/gh-sherpa architecture

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

- Interactive diagram: https://gitdiagram.com/inditextech/gh-sherpa
- Repository: https://github.com/inditextech/gh-sherpa

## Overview

##### Main Components
- CLI Interface: Represent the extension’s entry points under the “cmd” directory (e.g., create_branch, create_pull_request, root.go). These handle user commands and trigger the extension’s behavior.
- Configuration Management: Highlight the configuration components found under “internal/config” (configuration parsing, default-config.yml, templates, and custom configuration support from $HOME/.config/sherpa/config.yml). This part is crucial since it maps issue types to branch naming conventions.
- Use Cases/Business Logic: Emphasize the “internal/use_cases” where core functions (like create_branch and create_pull_request) are implemented. These files define how user commands drive the creation of branches and PRs.
- Domain Entities: Show the “internal/domain” layer where domain models (issue, branch, pull request, repository, issue type) are defined. These represent the business objects that the system manipulates.
- External Dependencies/Integrations:
- Git and GitHub: The “internal/git” and “internal/gh” packages encapsulate interactions with Git repositories and GitHub CLI respectively.
- Issue Trackers: The packages under “internal/issue_trackers” (with separate modules for GitHub and Jira) represent connectors to external issue tracking systems.
- Auxiliary Components:
- Fakes and Mocks (found in “internal/fakes” and “internal/mocks”) that facilitate testing.
- Validation and Metadata (in the “pkg” directory) to enforce rules and capture repository metadata.

##### Inter-component Relationships
- The CLI commands (in the cmd directory) act as the entry point. They interact with the Use Cases – for instance, the “create_branch” and “create_pull_request” use cases – which in turn coordinate domain logic.
- The Use Cases leverage the Configuration Management to determine the issue-to-branch mapping logic.
- Domain entities pass data between the use cases and integration modules (Git, GitHub CLI, or issue trackers).
- There is a clear separation between the logic that handles business rules (internal/use_cases and internal/domain) and the actual integrations (internal/git, internal/gh, internal/issue_trackers/*).

##### Architectural Patterns and Design Principles
- Layered Architecture: The project cleanly separates concerns into a command layer (CLI), application layer (use cases and domain logic), and infrastructure layer (Git and issue tracker integrations).
- Dependency Inversion: The use of interfaces and “fakes” in internal/fakes/mocks helps in abstracting external dependencies, which facilitates testing and potentially plug-and-play integrations.
- Extensibility: The configuration management, templated configuration files, and structured domain objects suggest that the tool is built to be easily extended (for instance, to support other issue trackers or customized branching schemes).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Interface"
        CLI["CLI Commands (cmd/)"]:::cli
    end

    %% Application Layer
    subgraph "Application Layer"
        UC["Use Cases (internal/use_cases)"]:::business
        CONFIG["Configuration Management (internal/config)"]:::config
        DOMAIN["Domain Entities (internal/domain)"]:::domain
    end

    %% Integrations Layer
    subgraph "Integrations"
        GIT["Git Operations (internal/git)"]:::integration
        GH["GitHub CLI (internal/gh)"]:::integration
        subgraph "Issue Trackers"
            GITHUBIT["GitHub Issue Tracker (internal/issue_trackers/github)"]:::integration
            JIRA["Jira Issue Tracker (internal/issue_trackers/jira)"]:::integration
        end
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        LOG["Logging (internal/logging)"]:::auxiliary
        FAKES["Fakes (internal/fakes)"]:::auxiliary
        MOCKS["Mocks (internal/mocks)"]:::auxiliary
        VALID["Validation (pkg/validator)"]:::auxiliary
        META["Metadata (pkg/metadata)"]:::auxiliary
    end

    %% Connections
    CLI -->|"triggers"| UC
    UC -->|"reads"| CONFIG
    UC -->|"executes with"| DOMAIN
    UC -->|"calls"| GIT
    UC -->|"calls"| GH
    UC -->|"interfaces with"| GITHUBIT
    UC -->|"interfaces with"| JIRA
    UC -->|"logs via"| LOG
    DOMAIN -->|"validated by"| VALID
    DOMAIN -->|"augmented by"| META

    %% Click Events
    click CLI "https://github.com/inditextech/gh-sherpa/tree/main/cmd/"
    click CONFIG "https://github.com/inditextech/gh-sherpa/tree/main/internal/config/"
    click UC "https://github.com/inditextech/gh-sherpa/tree/main/internal/use_cases/"
    click DOMAIN "https://github.com/inditextech/gh-sherpa/tree/main/internal/domain/"
    click GIT "https://github.com/inditextech/gh-sherpa/tree/main/internal/git/"
    click GH "https://github.com/inditextech/gh-sherpa/tree/main/internal/gh/"
    click GITHUBIT "https://github.com/inditextech/gh-sherpa/tree/main/internal/issue_trackers/github/"
    click JIRA "https://github.com/inditextech/gh-sherpa/tree/main/internal/issue_trackers/jira/"
    click LOG "https://github.com/inditextech/gh-sherpa/tree/main/internal/logging/"
    click FAKES "https://github.com/inditextech/gh-sherpa/tree/main/internal/fakes/"
    click MOCKS "https://github.com/inditextech/gh-sherpa/tree/main/internal/mocks/"
    click VALID "https://github.com/inditextech/gh-sherpa/tree/main/pkg/validator/"
    click META "https://github.com/inditextech/gh-sherpa/tree/main/pkg/metadata/"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef business fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef config fill:#FFC107,stroke:#000,stroke-width:2px;
    classDef domain fill:#FFECB3,stroke:#000,stroke-width:2px;
    classDef integration fill:#F08080,stroke:#000,stroke-width:2px;
    classDef auxiliary fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
