# mubbie/stacksmith architecture

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

- Interactive diagram: https://gitdiagram.com/mubbie/stacksmith
- Repository: https://github.com/mubbie/stacksmith

## Overview

##### Project type and purpose
- This is a Go-based CLI application (with a fallback Bash script) for managing “stacked” Git branches and PRs. It provides both a simple menu UI and a richer TUI (terminal UI) built on Bubble Tea and Lip Gloss.

##### Top-level architecture and file structure analysis
- cmd/            → command definitions and entry points
- internal/       → core logic (git operations, caching, error handling), configuration, logging, rendering, UI implementations
- pkg/plugins/    → plugin interface and loading
- scripts/        → standalone Bash version (stacksmith-lite.sh)
- build/          → completion scripts, installer definitions
- assets/         → static ANSI art and UI tapes
- docs/           → planning and roadmap
- main.go         → root of the Go edition CLI
- Makefile, goreleaser.yaml → build and release automation

##### Main components
a. CLI Entrypoint
- main.go → invokes cmd/root.go (cobra or custom parser)
- cmd/\*.go → individual commands: stack, sync, push, fixpr, graph, tui, completion
b. Core Service Layer (internal/core)
- git.go: wraps vanilla Git operations (rebase, push, branch stacking)
- cache.go, stack.go, errors.go: business logic for managing stacks
c. Configuration & Logging
- internal/config/config.go: loads user config (flags, env vars, config files)
- internal/logger/logger.go: structured logging backend
d. Rendering & UI
- internal/render/printer.go: plain-text output for non-interactive commands
- internal/ui/simplemenu: lightweight menu prompts for menu-based flows
- internal/ui/fulltui: Bubble Tea models, views, status bars, DAG renderer
- internal/ui/styles: shared styling definitions
e. Plugin System
- pkg/plugins/plugins.go: plugin registration and hook points
f. Bash fallback
- scripts/stacksmith-lite.sh: zero-dependency script for minimal environments
g. Build & Release
- build/completions: auto-generated shell completions
- build/installer: Windows installer scripts (InnoSetup)
- goreleaser.yaml & Makefile: cross-platform build, release, packaging

##### Relationships and data flows
- User runs `stacksmith <command>` → main.go → cmd/<command>.Run
- Command layer invokes internal/config to load settings → internal/logger to initialize logs
- Business logic in internal/core performs Git operations (executes `git` under the hood)
- Results flow to either internal/render for stdout printing or to internal/ui for interactive flows
- internal/ui produces terminal UI frames and handles user events → may call back into core for further operations
- pkg/plugins can inject or extend commands or hooks into core workflows
- build pipeline reads cmd/ and internal/ to compile Go binaries, then generates completions and installers

##### Architectural patterns & design principles
- Layered architecture (entrypoint → config → core → render/UI → external Git)
- Modular commands (each subcommand isolated under cmd/)
- Separation of concerns: core logic vs. UI vs. config vs. logging
- Plugin extensibility via pkg/plugins
- Build automation via Makefile and GoReleaser

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        main["main.go"]:::cli
        root["cmd/root.go"]:::cli
        stackCmd["cmd/stack.go"]:::cli
        syncCmd["cmd/sync.go"]:::cli
        pushCmd["cmd/push.go"]:::cli
        fixprCmd["cmd/fixpr.go"]:::cli
        graphCmd["cmd/graph.go"]:::cli
        tuiCmd["cmd/tui.go"]:::cli
        completionCmd["cmd/completion.go"]:::cli
    end

    %% Config & Logging
    subgraph "Config & Logging"
        config["internal/config/config.go"]:::config
        logger["internal/logger/logger.go"]:::config
    end

    %% Core Service Layer
    subgraph "Core Service Layer"
        gitCore["internal/core/git.go"]:::core
        stackCore["internal/core/stack.go"]:::core
        cacheCore["internal/core/cache.go"]:::core
        errorsCore["internal/core/errors.go"]:::core
    end

    %% Rendering & UI
    subgraph "Rendering & UI"
        subgraph "Plain-text Rendering"
            printer["internal/render/printer.go"]:::render
        end
        subgraph "Simple Menu UI"
            basePrompt["baseprompt.go"]:::ui
            menuSM["menu.go"]:::ui
            listSM["list.go"]:::ui
            stackPrompt["stack_prompt.go"]:::ui
            syncPrompt["sync_prompt.go"]:::ui
            fixprPrompt["fixpr_prompt.go"]:::ui
        end
        subgraph "Full TUI (Bubble Tea & Lip Gloss)"
            modelFT["model.go"]:::ui
            viewFT["view.go"]:::ui
            updateFT["update.go"]:::ui
            statusbarFT["statusbar.go"]:::ui
            dagFT["dag.go"]:::ui
            stylesFT["styles.go"]:::ui
            stylesShared["styles.go"]:::ui
        end
    end

    %% Plugin System
    plugin["pkg/plugins/plugins.go"]:::plugin

    %% Bash Fallback
    bash["scripts/stacksmith-lite.sh"]:::infra

    %% External Git
    externalGit["Git CLI"]:::infra

    %% Build & Release Pipeline
    subgraph "Build & Release Pipeline"
        completionsBash["stacksmith.bash"]:::build
        completionsFish["stacksmith.fish"]:::build
        completionsZsh["stacksmith.zsh"]:::build
        installer["setup.iss"]:::build
        makefile["Makefile"]:::build
        goreleaser[".goreleaser.yaml"]:::build
        buildArtifacts["Go Binary & Artifacts"]:::build
    end

    %% User
    user["User"]:::external

    %% Connections
    user -->|"1: invoke stacksmith"| main
    main --> root
    root --> config
    root --> logger
    root --> stackCmd
    root --> syncCmd
    root --> pushCmd
    root --> fixprCmd
    root --> graphCmd
    root --> tuiCmd
    root --> completionCmd

    stackCmd -->|"load config"| config
    syncCmd -->|"load config"| config
    pushCmd --> config
    fixprCmd --> config
    graphCmd --> config
    tuiCmd --> config
    completionCmd --> config

    stackCmd -->|"executes"| stackCore
    syncCmd -->|"executes"| stackCore
    pushCmd -->|"executes"| gitCore
    fixprCmd -->|"executes"| gitCore
    graphCmd -->|"executes"| stackCore
    tuiCmd -->|"interactive"| modelFT

    stackCore --> cacheCore
    stackCore --> errorsCore
    gitCore --> externalGit

    stackCore --> printer
    stackCore --> modelFT
    printer -->|"output"| user

    modelFT -->|"render"| viewFT
    modelFT --> statusbarFT
    modelFT --> dagFT

    %% UI simple menu flows
    stackPrompt --> basePrompt
    syncPrompt --> basePrompt
    fixprPrompt --> basePrompt

    %% Plugin hook
    root --> plugin
    plugin --> stackCore
    plugin --> gitCore

    %% Bash fallback flow
    user -->|"fallback"| bash
    bash --> externalGit

    %% Build pipeline flow
    makefile --> buildArtifacts
    goreleaser --> buildArtifacts
    buildArtifacts --> user
    makefile --> completionsBash
    makefile --> completionsFish
    makefile --> completionsZsh
    makefile --> installer

    %% Click Events
    click main "https://github.com/mubbie/stacksmith/blob/main/main.go"
    click root "https://github.com/mubbie/stacksmith/blob/main/cmd/root.go"
    click stackCmd "https://github.com/mubbie/stacksmith/blob/main/cmd/stack.go"
    click syncCmd "https://github.com/mubbie/stacksmith/blob/main/cmd/sync.go"
    click pushCmd "https://github.com/mubbie/stacksmith/blob/main/cmd/push.go"
    click fixprCmd "https://github.com/mubbie/stacksmith/blob/main/cmd/fixpr.go"
    click graphCmd "https://github.com/mubbie/stacksmith/blob/main/cmd/graph.go"
    click tuiCmd "https://github.com/mubbie/stacksmith/blob/main/cmd/tui.go"
    click completionCmd "https://github.com/mubbie/stacksmith/blob/main/cmd/completion.go"
    click gitCore "https://github.com/mubbie/stacksmith/blob/main/internal/core/git.go"
    click stackCore "https://github.com/mubbie/stacksmith/blob/main/internal/core/stack.go"
    click cacheCore "https://github.com/mubbie/stacksmith/blob/main/internal/core/cache.go"
    click errorsCore "https://github.com/mubbie/stacksmith/blob/main/internal/core/errors.go"
    click config "https://github.com/mubbie/stacksmith/blob/main/internal/config/config.go"
    click logger "https://github.com/mubbie/stacksmith/blob/main/internal/logger/logger.go"
    click printer "https://github.com/mubbie/stacksmith/blob/main/internal/render/printer.go"
    click basePrompt "https://github.com/mubbie/stacksmith/blob/main/internal/ui/simplemenu/baseprompt.go"
    click menuSM "https://github.com/mubbie/stacksmith/blob/main/internal/ui/simplemenu/menu.go"
    click listSM "https://github.com/mubbie/stacksmith/blob/main/internal/ui/simplemenu/list.go"
    click stackPrompt "https://github.com/mubbie/stacksmith/blob/main/internal/ui/simplemenu/stack_prompt.go"
    click syncPrompt "https://github.com/mubbie/stacksmith/blob/main/internal/ui/simplemenu/sync_prompt.go"
    click fixprPrompt "https://github.com/mubbie/stacksmith/blob/main/internal/ui/simplemenu/fixpr_prompt.go"
    click modelFT "https://github.com/mubbie/stacksmith/blob/main/internal/ui/fulltui/model.go"
    click viewFT "https://github.com/mubbie/stacksmith/blob/main/internal/ui/fulltui/view.go"
    click updateFT "https://github.com/mubbie/stacksmith/blob/main/internal/ui/fulltui/update.go"
    click statusbarFT "https://github.com/mubbie/stacksmith/blob/main/internal/ui/fulltui/statusbar.go"
    click dagFT "https://github.com/mubbie/stacksmith/blob/main/internal/ui/fulltui/dag.go"
    click stylesFT "https://github.com/mubbie/stacksmith/blob/main/internal/ui/fulltui/styles.go"
    click stylesShared "https://github.com/mubbie/stacksmith/blob/main/internal/ui/styles/styles.go"
    click plugin "https://github.com/mubbie/stacksmith/blob/main/pkg/plugins/plugins.go"
    click bash "https://github.com/mubbie/stacksmith/blob/main/scripts/stacksmith-lite.sh"
    click completionsBash "https://github.com/mubbie/stacksmith/blob/main/build/completions/stacksmith.bash"
    click completionsFish "https://github.com/mubbie/stacksmith/blob/main/build/completions/stacksmith.fish"
    click completionsZsh "https://github.com/mubbie/stacksmith/blob/main/build/completions/stacksmith.zsh"
    click installer "https://github.com/mubbie/stacksmith/blob/main/build/installer/setup.iss"
    click makefile "https://github.com/mubbie/stacksmith/tree/main/Makefile"
    click goreleaser "https://github.com/mubbie/stacksmith/blob/main/.goreleaser.yaml"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef config fill:#E8F5E9,stroke:#388E3C,color:#2E7D32
    classDef core fill:#E8F5E9,stroke:#388E3C,color:#2E7D32
    classDef render fill:#FFF8E1,stroke:#F9A825,color:#F57F17
    classDef ui fill:#FFF8E1,stroke:#F9A825,color:#F57F17
    classDef plugin fill:#FFF3E0,stroke:#FB8C00,color:#EF6C00
    classDef infra fill:#ECEFF1,stroke:#90A4AE,color:#546E7A
    classDef build fill:#F3E5F5,stroke:#8E24AA,color:#6A1B9A
    classDef external fill:#CFD8DC,stroke:#607D8B,color:#455A64
```
