# alecthomas/kong architecture

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

- Interactive diagram: https://gitdiagram.com/alecthomas/kong
- Repository: https://github.com/alecthomas/kong

## Overview

Kong is a Go library for turning a Go struct and its tags into a command-line interface. The main workflow starts when an application supplies its CLI structure and arguments: Kong builds a command model, scans and parses input into a Context, maps values, validates them, and makes the selected command available to run. Separate capabilities include generated contextual help, custom decoders, configuration and external defaults, hooks, dynamic commands, and dependency injection. The graph follows README-documented behavior and sampled files; unsampled implementation details are not asserted.

Main entry points: [`context.go`](https://github.com/alecthomas/kong/blob/master/context.go) (Parse context), [`options.go`](https://github.com/alecthomas/kong/blob/master/options.go) (Configuration options), [`kong.go`](https://github.com/alecthomas/kong/blob/master/kong.go) (Kong API), [`build.go`](https://github.com/alecthomas/kong/blob/master/build.go) (Model builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_definition["CLI Definition"]
  node_builder["Model builder<br/>[build.go]"]
  node_tags["Tag metadata<br/>[tag.go]"]
end

subgraph group_execution["Parse And Execute"]
  node_entry["Kong API<br/>[kong.go]"]
  node_scanner["Argument scanner<br/>[scanner.go]"]
  node_context["Parse context<br/>[context.go]"]
  node_mapper["Value decoders<br/>[mapper.go]"]
  node_callbacks["Command callbacks<br/>[callbacks.go]"]
end

subgraph group_customization["Customization"]
  node_options["Configuration options<br/>[options.go]"]
  node_resolver["Default resolvers<br/>[resolver.go]"]
  node_hooks["Lifecycle hooks<br/>[hooks.go]"]
  node_interpolation["Variable interpolation<br/>[interpolate.go]"]
end

subgraph group_presentation["Help And Errors"]
  node_help["Contextual help<br/>[help.go]"]
  node_errors["Parse errors<br/>[error.go]"]
end

node_developer(("Application developer"))
node_user(("CLI user"))

node_developer -->|"defines CLI"| node_entry
node_user -->|"supplies arguments"| node_entry
node_entry -->|"builds model"| node_builder
node_builder -.->|"reads tags"| node_tags
node_entry -->|"parses input"| node_context
node_context -->|"scans arguments"| node_scanner
node_context -.->|"decodes values"| node_mapper
node_context -->|"resolves defaults"| node_resolver
node_context -->|"prints help"| node_help
node_context -.->|"reports errors"| node_errors
node_context -->|"runs command"| node_callbacks
node_developer -->|"configures behavior"| node_options
node_options -->|"loads configuration"| node_resolver
node_options -->|"registers decoders"| node_mapper
node_options -->|"registers hooks"| node_hooks
node_options -.->|"configures variables"| node_interpolation
node_help -->|"interpolates text"| node_interpolation

click node_entry "https://github.com/alecthomas/kong/blob/master/kong.go"
click node_builder "https://github.com/alecthomas/kong/blob/master/build.go"
click node_tags "https://github.com/alecthomas/kong/blob/master/tag.go"
click node_scanner "https://github.com/alecthomas/kong/blob/master/scanner.go"
click node_context "https://github.com/alecthomas/kong/blob/master/context.go"
click node_mapper "https://github.com/alecthomas/kong/blob/master/mapper.go"
click node_callbacks "https://github.com/alecthomas/kong/blob/master/callbacks.go"
click node_options "https://github.com/alecthomas/kong/blob/master/options.go"
click node_resolver "https://github.com/alecthomas/kong/blob/master/resolver.go"
click node_hooks "https://github.com/alecthomas/kong/blob/master/hooks.go"
click node_interpolation "https://github.com/alecthomas/kong/blob/master/interpolate.go"
click node_help "https://github.com/alecthomas/kong/blob/master/help.go"
click node_errors "https://github.com/alecthomas/kong/blob/master/error.go"

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_builder,node_tags,node_user toneBlue
class node_entry,node_scanner,node_context,node_mapper,node_callbacks toneAmber
class node_options,node_resolver,node_hooks,node_interpolation toneMint
class node_help,node_errors toneRose
class node_developer toneIndigo
```

## Components

### CLI Definition

- [Model builder](https://github.com/alecthomas/kong/blob/master/build.go): `build.go`
- [Tag metadata](https://github.com/alecthomas/kong/blob/master/tag.go): `tag.go`

### Parse And Execute

- [Kong API](https://github.com/alecthomas/kong/blob/master/kong.go): `kong.go`
- [Argument scanner](https://github.com/alecthomas/kong/blob/master/scanner.go): `scanner.go`
- [Parse context](https://github.com/alecthomas/kong/blob/master/context.go): `context.go`
- [Value decoders](https://github.com/alecthomas/kong/blob/master/mapper.go): `mapper.go`
- [Command callbacks](https://github.com/alecthomas/kong/blob/master/callbacks.go): `callbacks.go`

### Customization

- [Configuration options](https://github.com/alecthomas/kong/blob/master/options.go): `options.go`
- [Default resolvers](https://github.com/alecthomas/kong/blob/master/resolver.go): `resolver.go`
- [Lifecycle hooks](https://github.com/alecthomas/kong/blob/master/hooks.go): `hooks.go`
- [Variable interpolation](https://github.com/alecthomas/kong/blob/master/interpolate.go): `interpolate.go`

### Help And Errors

- [Contextual help](https://github.com/alecthomas/kong/blob/master/help.go): `help.go`
- [Parse errors](https://github.com/alecthomas/kong/blob/master/error.go): `error.go`

### Other components

- **Application developer**
- **CLI user**

## Connections

- Application developer → Kong API: defines CLI (evidence: `README.md`)
- CLI user → Kong API: supplies arguments (evidence: `README.md`)
- Kong API → Model builder: builds model (evidence: `README.md`)
- Model builder → Tag metadata: reads tags
- Kong API → Parse context: parses input (evidence: `README.md`)
- Parse context → Argument scanner: scans arguments (evidence: `context.go`)
- Parse context → Value decoders: decodes values
- Parse context → Default resolvers: resolves defaults (evidence: `README.md`)
- Parse context → Contextual help: prints help (evidence: `README.md`)
- Parse context → Parse errors: reports errors
- Parse context → Command callbacks: runs command (evidence: `README.md`)
- Application developer → Configuration options: configures behavior (evidence: `README.md`)
- Configuration options → Default resolvers: loads configuration (evidence: `options.go`)
- Configuration options → Value decoders: registers decoders (evidence: `options.go`)
- Configuration options → Lifecycle hooks: registers hooks (evidence: `options.go`)
- Configuration options → Variable interpolation: configures variables
- Contextual help → Variable interpolation: interpolates text (evidence: `README.md`)
