# meso1007/tagoly architecture

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

- Interactive diagram: https://gitdiagram.com/meso1007/tagoly
- Repository: https://github.com/meso1007/tagoly

## Overview

1. **Project shape**
   Tagoly is a single-binary Go CLI for Git commit authoring and validation. There is no server component: the runtime boundary is the local terminal, the local Git repository, and the user’s filesystem.

2. **CLI entrypoint and command routing**
   `cmd/tagoly/main.go` is the top-level entrypoint. The other files under `cmd/tagoly/` split the executable into subcommands: interactive commit flow, linting, search, tag dictionary browsing, and hook installation. This is the main surface an architecture diagram should start from.

3. **Interactive commit creation flow**
   The core “write a commit” path is: staged files are inspected, candidate scopes are derived, the user is prompted for type/scope/subject, and a final commit message is assembled in `type(scope): subject` form. The prompt layer is interactive and terminal-driven, while the generation logic lives in internal packages.

4. **Scope detection and message synthesis**
   `internal/generator/scope.go` is responsible for turning staged file paths into likely commit scopes. This is one of the main differentiators of the tool: it reduces manual input by deriving scope suggestions from repository structure, then feeds those suggestions into the prompt flow.

5. **Git repository boundary**
   `internal/git/git.go` is the abstraction layer for talking to Git itself. It is the bridge to repository state and history, likely wrapping operations such as reading staged changes, inspecting commit logs, and invoking commit-related Git commands. All higher-level features depend on this package rather than calling Git directly.

6. **Commit message parsing and validation**
   `internal/parser/parser.go` and `internal/lint/lint.go` form the validation boundary. Parser logic understands Tagoly’s commit format, and linting checks that a message or commit range conforms to the expected convention. This validation is reused by the CLI and by the Git hook.

7. **Hook installation and enforcement**
   `internal/hook/hook.go` manages installation of a `commit-msg` hook into `.git/hooks/`. The hook’s job is enforcement: it runs Tagoly lint against the commit message file before the commit is accepted. This keeps policy local to the repository without requiring a central service.

8. **Search and tag dictionary features**
   `internal/search/search.go` supports querying commit history by type, scope, subject, and limits. `cmd/tagoly/tagdict.go` exposes the “tag dictionary” experience, which is an interactive way to browse commit types or scopes. These features are read-only over existing Git history, unlike the commit flow.

9. **Custom configuration boundary**
   `internal/config/config.go` loads custom commit tags from `.tagolycustom` in the repository root, with a fallback to `~/.tagolycustom`. This is the only explicit configuration input shown in the repo and it influences the tag/type choices available in prompts and validation.

10. **Operational and distribution layer**
   The repo is packaged and released as a Go CLI using `goreleaser` (`.goreleaser.yaml`) and GitHub Actions (`.github/workflows/release.yml`). Shell scripts like `build.sh`, `install.sh`, and `test_syntax.sh` support local build/test/release workflows, but they do not change the runtime architecture.

11. **Primary data flow to diagram**
   The main runtime flow is: user input + staged Git state + optional `.tagolycustom` config → scope/type suggestion and prompt → commit message generation → Git commit or lint/hook validation. Search and tagdict branch off from the same Git history and parsing layers but do not write to the repository.

12. **Important architectural boundaries**
   The key boundaries are: terminal/UI vs. core logic, core logic vs. Git repository access, validation vs. enforcement via hook, and repository-local config vs. user-home fallback config. There are no external APIs or databases involved in normal operation.

Main entry points: [`cmd/tagoly/main.go`](https://github.com/meso1007/tagoly/blob/main/cmd/tagoly/main.go) (tagoly), [`internal/search/search.go`](https://github.com/meso1007/tagoly/blob/main/internal/search/search.go) (History search), [`internal/lint/lint.go`](https://github.com/meso1007/tagoly/blob/main/internal/lint/lint.go) (Lint), [`internal/git/git.go`](https://github.com/meso1007/tagoly/blob/main/internal/git/git.go) (Git bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI surface"]
  node_cmd_main["tagoly<br/>cli entrypoint<br/>[main.go]"]
  node_cmd_lint["Lint<br/>subcommand<br/>[lint.go]"]
  node_cmd_search["Search<br/>subcommand<br/>[search.go]"]
  node_cmd_tagdict["Tag dict<br/>subcommand<br/>[tagdict.go]"]
  node_cmd_hook["Hook<br/>subcommand<br/>[hook.go]"]
  node_search{{"History search<br/>history query<br/>[search.go]"}}
end

subgraph group_core["Core flow"]
  node_prompt(("Prompt<br/>interactive ui<br/>[prompt.go]"))
  node_scope_gen{{"Scope gen<br/>scope inference<br/>[scope.go]"}}
end

subgraph group_repo["Git boundary"]
  node_git[("Git bridge<br/>git adapter<br/>[git.go]")]
end

subgraph group_policy["Validation"]
  node_parser["Parser<br/>[parser.go]"]
  node_lint{{"Lint<br/>policy engine<br/>[lint.go]"}}
  node_hook["Hook<br/>[hook.go]"]
end

subgraph group_config["Configuration"]
  node_config["Config<br/>[config.go]"]
end

subgraph group_delivery["Delivery"]
  node_release_yaml["Release yaml<br/>release config<br/>[.goreleaser.yaml]"]
  node_release_workflow["Release workflow<br/>ci workflow<br/>[release.yml]"]
end

node_cmd_main -->|"routes to"| node_cmd_lint
node_cmd_main -->|"routes to"| node_cmd_search
node_cmd_main -->|"routes to"| node_cmd_tagdict
node_cmd_main -->|"routes to"| node_cmd_hook
node_cmd_main -->|"drives"| node_prompt
node_prompt -->|"asks for scopes"| node_scope_gen
node_scope_gen -->|"reads staged files"| node_git
node_prompt -->|"loads tags"| node_config
node_cmd_lint -->|"invokes"| node_lint
node_cmd_search -->|"invokes"| node_search
node_cmd_tagdict -->|"shares history"| node_search
node_cmd_hook -->|"installs"| node_hook
node_lint -->|"parses"| node_parser
node_lint -->|"reads history"| node_git
node_search -->|"reads history"| node_git
node_search -->|"matches format"| node_parser
node_hook -->|"enforces"| node_lint
node_hook -->|"installs into repo"| node_git
node_parser -->|"uses tags"| node_config
node_release_yaml -->|"drives"| node_release_workflow

click node_cmd_main "https://github.com/meso1007/tagoly/blob/main/cmd/tagoly/main.go"
click node_cmd_lint "https://github.com/meso1007/tagoly/blob/main/cmd/tagoly/lint.go"
click node_cmd_search "https://github.com/meso1007/tagoly/blob/main/cmd/tagoly/search.go"
click node_cmd_tagdict "https://github.com/meso1007/tagoly/blob/main/cmd/tagoly/tagdict.go"
click node_cmd_hook "https://github.com/meso1007/tagoly/blob/main/cmd/tagoly/hook.go"
click node_prompt "https://github.com/meso1007/tagoly/blob/main/internal/prompt/prompt.go"
click node_scope_gen "https://github.com/meso1007/tagoly/blob/main/internal/generator/scope.go"
click node_git "https://github.com/meso1007/tagoly/blob/main/internal/git/git.go"
click node_parser "https://github.com/meso1007/tagoly/blob/main/internal/parser/parser.go"
click node_lint "https://github.com/meso1007/tagoly/blob/main/internal/lint/lint.go"
click node_hook "https://github.com/meso1007/tagoly/blob/main/internal/hook/hook.go"
click node_config "https://github.com/meso1007/tagoly/blob/main/internal/config/config.go"
click node_search "https://github.com/meso1007/tagoly/blob/main/internal/search/search.go"
click node_release_yaml "https://github.com/meso1007/tagoly/blob/main/.goreleaser.yaml"
click node_release_workflow "https://github.com/meso1007/tagoly/blob/main/.github/workflows/release.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_main,node_cmd_lint,node_cmd_search,node_cmd_tagdict,node_cmd_hook,node_search toneBlue
class node_prompt,node_scope_gen toneAmber
class node_git toneMint
class node_parser,node_lint,node_hook toneRose
class node_config toneIndigo
class node_release_yaml,node_release_workflow toneTeal
```

## Components

### CLI surface

Executable entrypoints and subcommands exposed to the terminal.

- [tagoly](https://github.com/meso1007/tagoly/blob/main/cmd/tagoly/main.go): cli entrypoint · Top-level command router for the binary. · `cmd/tagoly/main.go`
- [Lint](https://github.com/meso1007/tagoly/blob/main/cmd/tagoly/lint.go): subcommand · CLI path for validating commit messages or ranges. · `cmd/tagoly/lint.go`
- [Search](https://github.com/meso1007/tagoly/blob/main/cmd/tagoly/search.go): subcommand · CLI path for querying commit history. · `cmd/tagoly/search.go`
- [Tag dict](https://github.com/meso1007/tagoly/blob/main/cmd/tagoly/tagdict.go): subcommand · Interactive browsing of commit tags and scopes. · `cmd/tagoly/tagdict.go`
- [Hook](https://github.com/meso1007/tagoly/blob/main/cmd/tagoly/hook.go): subcommand · CLI path for hook installation. · `cmd/tagoly/hook.go`
- [History search](https://github.com/meso1007/tagoly/blob/main/internal/search/search.go): history query · Queries commit history by type, scope, subject, and limits. · `internal/search/search.go`

### Core flow

Interactive commit authoring and scope suggestion.

- [Prompt](https://github.com/meso1007/tagoly/blob/main/internal/prompt/prompt.go): interactive ui · Terminal prompts for type, scope, and subject. · `internal/prompt/prompt.go`
- [Scope gen](https://github.com/meso1007/tagoly/blob/main/internal/generator/scope.go): scope inference · Derives likely scopes from staged file paths. · `internal/generator/scope.go`

### Git boundary

Repository-state access and history reads.

- [Git bridge](https://github.com/meso1007/tagoly/blob/main/internal/git/git.go): git adapter · Wraps repository state, staged files, and history access. · `internal/git/git.go`

### Validation

Parsing, linting, and hook enforcement of commit policy.

- [Parser](https://github.com/meso1007/tagoly/blob/main/internal/parser/parser.go): message parser · Understands Tagoly commit message structure. · `internal/parser/parser.go`
- [Lint](https://github.com/meso1007/tagoly/blob/main/internal/lint/lint.go): policy engine · Checks commit messages and commit ranges against the convention. · `internal/lint/lint.go`
- [Hook](https://github.com/meso1007/tagoly/blob/main/internal/hook/hook.go): git hook · Installs and runs commit-msg enforcement locally. · `internal/hook/hook.go`

### Configuration

Repository-local and user-home tag configuration.

- [Config](https://github.com/meso1007/tagoly/blob/main/internal/config/config.go): tag config · Loads custom tags from repository or home-directory config. · `internal/config/config.go`

### Delivery

Release and packaging automation.

- [Release yaml](https://github.com/meso1007/tagoly/blob/main/.goreleaser.yaml): release config · GoReleaser packaging and release definition. · `.goreleaser.yaml`
- [Release workflow](https://github.com/meso1007/tagoly/blob/main/.github/workflows/release.yml): ci workflow · GitHub Actions release automation. · `.github/workflows/release.yml`

## Connections

- tagoly → Lint: routes to · Top-level CLI dispatches lint command.
- tagoly → Search: routes to · Top-level CLI dispatches search command.
- tagoly → Tag dict: routes to · Top-level CLI dispatches tag dictionary browsing.
- tagoly → Hook: routes to · Top-level CLI dispatches hook installation.
- tagoly → Prompt: drives · Interactive commit flow starts from the CLI surface.
- Prompt → Scope gen: asks for scopes · Prompt layer consumes derived scope suggestions.
- Scope gen → Git bridge: reads staged files · Scope inference is based on repository state.
- Prompt → Config: loads tags · Custom tags influence prompt choices.
- Lint → Lint: invokes · Lint subcommand delegates to validation engine.
- Search → History search: invokes · Search subcommand delegates to history query layer.
- Tag dict → History search: shares history · Tag dictionary browsing reuses history/search primitives.
- Hook → Hook: installs · Hook subcommand delegates to hook management.
- Lint → Parser: parses · Validation depends on commit message parsing.
- Lint → Git bridge: reads history · Lint can validate commits or ranges from Git.
- History search → Git bridge: reads history · Search queries repository commit history.
- History search → Parser: matches format · Search may filter by parsed commit structure.
- Hook → Lint: enforces · Commit-msg hook runs lint before accepting commits.
- Hook → Git bridge: installs into repo · Hook management targets the local .git directory.
- Parser → Config: uses tags · Parsing and validation are informed by custom tag definitions.
- Release yaml → Release workflow: drives · Release config is consumed by CI packaging workflow.
