# nerdwalletoss/shepherd architecture

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

- Interactive diagram: https://gitdiagram.com/nerdwalletoss/shepherd
- Repository: https://github.com/nerdwalletoss/shepherd

## Overview

##### Main Components
- CLI Interface: The entry point (src/cli.ts) that parses commands (e.g., checkout, apply, commit, push, pr-preview, pr) and delegates work.
- Command Modules: Each subcommand (residing in src/commands) handles specific operations. For example, the “checkout” command not only clones repositories but also uses hooks to determine eligibility.
- Adapters: Found in src/adapters, these modules abstract away differences in version control systems (currently focusing on Git/GitHub). They handle repository searches, cloning operations, and API interactions.
- Services: Located in src/services (like the GitHub service), these components provide higher-level operations supporting the adapters.
- Migration Spec / Hooks Engine: Shepherd’s core logic centers around interpreting a migration spec (shepherd.yml) with various hooks (should_migrate, post_checkout, apply, pr_message). This part ties into the commands to decide whether and how to perform changes.
- Logger & Utilities: (src/logger and src/util) which help in error reporting, logging progress, and executing shell commands across repositories.
- Configuration & Environment Management: Environment variables (e.g., SHEPHERD_GITHUB_REPO_NAME, SHEPHERD_REPO_DIR) and configuration files (babel, tsconfig, ESLint config) that influence run-time behavior.

##### Interactions and Relationships
- The CLI parses arguments and invokes the respective command module.
- Each command (e.g., “checkout”, “apply”, “commit”) calls into:
- The Hook Executor that runs commands from the migration spec.
- The Adapter module to interact with Git repositories and, where necessary, GitHub API.
- Utility libraries to execute shell commands and perform file operations.
- From CLI → Command Modules → Adapters/Services → External Systems (e.g., Git, GitHub APIs)
- Hooks execute in a sequence where “should_migrate” determines eligibility, “post_checkout” sets up the repo, “apply” effects the change, and “pr_message” dynamically creates the PR description.
- Environment variables and the persisted state mechanism (via SHEPHERD_DATA_DIR) influence command processing.

##### Architectural Patterns & Design Principles
- Modular Design: The structure separates concerns into CLI parsing, command execution, version control handling, and utility functions.
- Adapter Pattern: The “adapter” folder and related services abstract external systems like GitHub so that the core migration logic doesn’t depend on a specific version control system.
- Declarative Configuration: Using the YAML migration spec (shepherd.yml), Shepherd follows a declarative approach where the “what to do” is separated from the “how to do it.”
- Command Pattern: Each operational step (checkout, apply, commit, etc.) is implemented as a discrete command module, ensuring clear separation of functionality.

- Optionally, include separate sections for “Development/Testing” components like E2E tests, examples, and fixtures to underscore comprehensive test coverage and sample migrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Application Layer
    subgraph "Core Application Layer"
        CLI("Shepherd CLI"):::core
        CMD("Command Modules (checkout, apply, commit, etc.)"):::core
        MS("Migration Spec & Hooks Engine"):::core
    end

    %% Adapters & Services Layer
    subgraph "Adapters & Services Layer"
        GA("Git Adapter"):::adapter
        GHA("GitHub Adapter"):::adapter
        GS("GitHub Service"):::service
    end

    %% Supporting Components
    subgraph "Supporting Components"
        LU("Logger & Utilities"):::support
        CONF("Configuration & Env Management"):::support
    end

    %% External Systems
    subgraph "External Systems"
        GIT("Git Repositories"):::external
        GITHUB("GitHub API"):::external
    end

    %% Development & Testing
    subgraph "Development & Testing"
        TEST("E2E, Fixtures & Examples"):::dev
    end

    %% Relationships
    CLI -->|"parses commands"| CMD
    CMD -->|"invokes hooks"| MS
    MS -->|"triggers commands"| CMD
    CMD -->|"calls"| GA
    GA -->|"clones/updates"| GIT
    CMD -->|"integrates with"| GHA
    GHA -->|"issues PRs"| GITHUB
    GHA -->|"utilizes"| GS
    LU -.-> CMD
    LU -.-> MS
    CONF -.-> CLI
    CONF -.-> CMD
    CONF -.-> MS
    TEST -.-> LU

    %% Styles
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef adapter fill:#fc9,stroke:#333,stroke-width:2px;
    classDef service fill:#fc9,stroke:#333,stroke-width:2px;
    classDef support fill:#cff,stroke:#333,stroke-width:2px;
    classDef external fill:#f66,stroke:#333,stroke-width:2px;
    classDef dev fill:#9f9,stroke:#333,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/nerdwalletoss/shepherd/blob/main/src/cli.ts"
    click CMD "https://github.com/nerdwalletoss/shepherd/tree/main/src/commands"
    click GA "https://github.com/nerdwalletoss/shepherd/blob/main/src/adapters/git.ts"
    click GHA "https://github.com/nerdwalletoss/shepherd/blob/main/src/adapters/github.ts"
    click GS "https://github.com/nerdwalletoss/shepherd/blob/main/src/services/github.ts"
    click MS "https://github.com/nerdwalletoss/shepherd/blob/main/src/util/migration-spec.ts"
    click LU "https://github.com/nerdwalletoss/shepherd/blob/main/src/logger/index.ts"
```
