# fromwau/klap architecture

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

- Interactive diagram: https://gitdiagram.com/fromwau/klap
- Repository: https://github.com/fromwau/klap

## Overview

klap is a reflection-free Kotlin Multiplatform CLI framework. A program declares a command tree and typed inputs with its builder DSL; argv is parsed into a typed invocation, then the selected action runs or a built-in response is rendered. The graph also preserves the documented help, completion, generated-docs, structured-JSON, validation, and error capabilities. Several rendering and execution paths are documented but not excerpted, so those edges cite the README; internal links use the source index or excerpts where available.

Main entry points: [`klap/src/commonMain/kotlin/com/fromwau/klap/Runner.kt`](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Runner.kt) (Run and exit), [`klap/src/commonMain/kotlin/com/fromwau/klap/Parser.kt`](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Parser.kt) (Parse orchestration), [`klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderImpl.kt`](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderImpl.kt) (Builder implementation), [`klap/src/commonMain/kotlin/com/fromwau/klap/Cli.kt`](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Cli.kt) (CLI tree)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_declaration["Command declaration"]
  node_builder["Builder DSL<br/>[CommandBuilder.kt]"]
  node_builderimpl["Builder implementation<br/>[BuilderImpl.kt]"]
  node_validation["Tree validation"]
  node_specs["Command and input specs<br/>[HolderSpec.kt]"]
  node_cli["CLI tree<br/>[Cli.kt]"]
end

subgraph group_parsing["Argument parsing"]
  node_parser["Parse orchestration<br/>[Parser.kt]"]
  node_scan["Token scanning<br/>[ArgvScan.kt]"]
  node_matching["Name matching<br/>[NameMatch.kt]"]
  node_sifting["Input resolution<br/>[Sifted.kt]"]
  node_binding["Value binding<br/>[Bind.kt]"]
end

subgraph group_execution["Execution and results"]
  node_invocation["Resolved invocation<br/>[Invocation.kt]"]
  node_action["Action scope<br/>[ActionScope.kt]"]
  node_runner["Run and exit<br/>[Runner.kt]"]
  node_errors["Typed CLI errors<br/>[CliError.kt]"]
end

subgraph group_presentation["Built-in output"]
  node_help["Help rendering<br/>[Help.kt]"]
  node_completion["Shell completion<br/>[Completion.kt]"]
  node_completionrender["Completion output<br/>[Completion.kt]"]
  node_docs["Generated docs<br/>[Docs.kt]"]
  node_json["JSON output<br/>[Json.kt]"]
end

node_programmer(("CLI author"))
node_argv(("Command-line user"))
node_terminal["Terminal"]

node_programmer -->|"declares commands"| node_builder
node_builder -->|"delegates to"| node_builderimpl
node_builderimpl -->|"validates tree"| node_validation
node_builderimpl -->|"creates specs"| node_specs
node_builderimpl -->|"builds tree"| node_cli
node_argv -->|"supplies arguments"| node_cli
node_cli -->|"parses input"| node_parser
node_parser -->|"scans tokens"| node_scan
node_scan -->|"matches names"| node_matching
node_parser -->|"resolves inputs"| node_sifting
node_parser -->|"binds values"| node_binding
node_parser -->|"returns invocation"| node_invocation
node_parser -->|"returns errors"| node_errors
node_invocation -->|"carries scope"| node_action
node_cli -->|"runs command"| node_runner
node_runner -->|"executes action"| node_action
node_runner -->|"renders help"| node_help
node_runner -->|"handles completion"| node_completion
node_completion -->|"renders candidates"| node_completionrender
node_runner -->|"renders docs"| node_docs
node_runner -->|"renders JSON"| node_json
node_help -.->|"styles output"| node_terminal
node_runner -.->|"writes output"| node_terminal

click node_builder "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/CommandBuilder.kt"
click node_builderimpl "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderImpl.kt"
click node_validation "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderValidation.kt"
click node_specs "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/spec/HolderSpec.kt"
click node_cli "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Cli.kt"
click node_parser "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Parser.kt"
click node_scan "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/ArgvScan.kt"
click node_matching "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/NameMatch.kt"
click node_sifting "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/Sifted.kt"
click node_binding "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/Bind.kt"
click node_invocation "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Invocation.kt"
click node_action "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/ActionScope.kt"
click node_runner "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Runner.kt"
click node_errors "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/CliError.kt"
click node_help "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Help.kt"
click node_completion "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Completion.kt"
click node_completionrender "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Completion.kt"
click node_docs "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Docs.kt"
click node_json "https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Json.kt"

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_builderimpl,node_validation,node_specs,node_cli,node_argv toneBlue
class node_parser,node_scan,node_matching,node_sifting,node_binding toneAmber
class node_invocation,node_action,node_runner,node_errors toneMint
class node_help,node_completion,node_completionrender,node_docs,node_json toneRose
class node_programmer,node_terminal toneIndigo
```

## Components

### Command declaration

- [Builder DSL](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/CommandBuilder.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/CommandBuilder.kt`
- [Builder implementation](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderImpl.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderImpl.kt`
- [Tree validation](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderValidation.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderValidation.kt`
- [Command and input specs](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/spec/HolderSpec.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/internal/spec/HolderSpec.kt`
- [CLI tree](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Cli.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/Cli.kt`

### Argument parsing

- [Parse orchestration](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Parser.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/Parser.kt`
- [Token scanning](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/ArgvScan.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/ArgvScan.kt`
- [Name matching](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/NameMatch.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/NameMatch.kt`
- [Input resolution](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/Sifted.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/Sifted.kt`
- [Value binding](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/Bind.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/Bind.kt`

### Execution and results

- [Resolved invocation](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Invocation.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/Invocation.kt`
- [Action scope](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/ActionScope.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/ActionScope.kt`
- [Run and exit](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Runner.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/Runner.kt`
- [Typed CLI errors](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/CliError.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/CliError.kt`

### Built-in output

- [Help rendering](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Help.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Help.kt`
- [Shell completion](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/Completion.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/Completion.kt`
- [Completion output](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Completion.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Completion.kt`
- [Generated docs](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Docs.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Docs.kt`
- [JSON output](https://github.com/fromwau/klap/blob/master/klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Json.kt): `klap/src/commonMain/kotlin/com/fromwau/klap/internal/render/Json.kt`

### Other components

- **CLI author**
- **Command-line user**
- **Terminal**

## Connections

- CLI author → Builder DSL: declares commands
- Builder DSL → Builder implementation: delegates to (evidence: `klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderImpl.kt`)
- Builder implementation → Tree validation: validates tree (evidence: `klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderImpl.kt`)
- Builder implementation → Command and input specs: creates specs (evidence: `klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderImpl.kt`)
- Builder implementation → CLI tree: builds tree (evidence: `klap/src/commonMain/kotlin/com/fromwau/klap/internal/builder/BuilderImpl.kt`)
- Command-line user → CLI tree: supplies arguments
- CLI tree → Parse orchestration: parses input (evidence: `klap/src/commonMain/kotlin/com/fromwau/klap/Parser.kt`)
- Parse orchestration → Token scanning: scans tokens (evidence: `klap/src/commonMain/kotlin/com/fromwau/klap/Parser.kt`)
- Token scanning → Name matching: matches names (evidence: `klap/src/commonMain/kotlin/com/fromwau/klap/internal/parse/ArgvScan.kt`)
- Parse orchestration → Input resolution: resolves inputs
- Parse orchestration → Value binding: binds values
- Parse orchestration → Resolved invocation: returns invocation (evidence: `klap/src/commonMain/kotlin/com/fromwau/klap/Parser.kt`)
- Parse orchestration → Typed CLI errors: returns errors (evidence: `klap/src/commonMain/kotlin/com/fromwau/klap/Parser.kt`)
- Resolved invocation → Action scope: carries scope (evidence: `klap/src/commonMain/kotlin/com/fromwau/klap/Invocation.kt`)
- CLI tree → Run and exit: runs command
- Run and exit → Action scope: executes action
- Run and exit → Help rendering: renders help
- Run and exit → Shell completion: handles completion
- Shell completion → Completion output: renders candidates (evidence: `klap/src/commonMain/kotlin/com/fromwau/klap/Completion.kt`)
- Run and exit → Generated docs: renders docs
- Run and exit → JSON output: renders JSON
- Help rendering → Terminal: styles output
- Run and exit → Terminal: writes output