# rafapear/ktflag architecture

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

- Interactive diagram: https://gitdiagram.com/rafapear/ktflag
- Repository: https://github.com/rafapear/ktflag

## Overview

##### Project type and purpose
- It’s not a client-server or full-stack app—rather, a reusable, embeddable JAR that you pull into your own Kotlin projects to wire up console commands.

##### File structure
- Top-level build using Gradle (`build.gradle`, `settings.gradle`, `gradlew`).
- Source under `src/main/kotlin/pt/rafap/ktflag`:
- Core parser: `CommandParser.kt`, `ParserConfig.kt`
- Command pattern: abstract `CommandImpl`, `CommandInfo`, `CommandRegister`
- Argument parsing: `CommandArgsParser.kt`, `CommandArg.kt`
- Help: `ImplHelp.kt` (built-in help command)
- Tests mirror the same structure under `src/test/kotlin/...`
- No external services or databases—pure in-process library.

##### Readme insights
- Mentions example usage (`runExample` task) and Dokka docs generation.
- Describes core types: `CommandImpl`, `CommandInfo`, `CommandResult`.

##### Main components & relationships
a. Components
- CLI Application (your `main()` or `runExample` entry point)
- CommandParser (core façade)
- CommandRegister (holds registered commands including `ImplHelp`)
- CommandArgsParser (tokenizer / validator)
- CommandImpl (interface for each command; you implement it)
- CommandInfo (metadata for each command)
- CommandResult (+ result types: SUCCESS, ERROR, INVALID_ARGS, UNKNOWN_COMMAND)
b. Interactions
1. **User Input →** CLI App reads raw string
2. **CLI App →** passes to `CommandParser.parseInputToResult(input, context)`
3. **Parser →** uses `ParserConfig` to initialize
4. **Parser →** looks up command in `CommandRegister` by name/alias
5. **Parser →** delegates raw tokens to `CommandArgsParser` (validates arg count)
6. **Parser →** invokes `CommandImpl.execute(...)`
7. **CommandImpl →** returns `CommandResult`
c. Architectural patterns / principles
- Command Pattern: `CommandImpl` encapsulates each operation
- Registry Pattern: central `CommandRegister` for dynamic lookup & suggestion
- Single Responsibility: parsing, metadata, execution, styling are separate modules
d. Key technologies
- Kotlin (JVM)
- Gradle wrapper for build/test
- Dokka for documentation
- JUnit/KotlinTest for unit tests

##### Putting it all together
- CommandParser
- CommandRegister
- CommandArgsParser
- ParserConfig
- ImplHelp
- Data flows: Input string → Tokenization → Execution → Styled output.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer layer
    CLIApp["Consumer Application\nCLI App (main)"]:::consumer
    CLIApp -->|"input string"| CommandParser

    %% Library boundary
    subgraph "KtFlag Library (JAR)"
        direction TB
        %% Core parsing & registry (blue)
        CommandParser["CommandParser"]:::core
        CommandRegister["CommandRegister"]:::core
        CommandArgsParser["CommandArgsParser"]:::core
        CommandInfo["CommandInfo"]:::core

        %% Utilities (orange)
        ParserConfig["ParserConfig"]:::util
        Colors["Colors"]:::util

        %% Implementations & results (green)
        CommandImpl["CommandImpl"]:::impl
        ImplHelp["ImplHelp"]:::impl
        CommandResult["CommandResult"]:::impl
        CommandResultType["CommandResultType"]:::impl

        %% Relationships
        CommandParser -->|"init config"| ParserConfig
        CommandParser -->|"lookup by name"| CommandRegister
        CommandRegister -->|"auto-register"| ImplHelp
        CommandRegister -->|"holds metadata"| CommandInfo
        CommandParser -->|"parse args"| CommandArgsParser
        CommandParser -->|"execute"| CommandImpl
        CommandImpl -->|"returns"| CommandResult
        CommandResult -->|"type"| CommandResultType
        CommandParser -->|"format output"| Colors
    end

    %% Consumer commands
    subgraph "Consumer Application"
        direction TB
        UserCommand["UserCommand\n(implements CommandImpl)"]:::impl
        CLIApp -->|"register"| UserCommand
        UserCommand -->|"registered in"| CommandRegister
        UserCommand -->|"execute"| CommandResult
    end

    %% Result back to consumer
    CommandResult -->|"styled output"| CLIApp

    %% Click Events
    click CommandParser "https://github.com/rafapear/ktflag/blob/master/src/main/kotlin/pt/rafap/ktflag/CommandParser.kt"
    click ParserConfig "https://github.com/rafapear/ktflag/blob/master/src/main/kotlin/pt/rafap/ktflag/ParserConfig.kt"
    click ImplHelp "https://github.com/rafapear/ktflag/blob/master/src/main/kotlin/pt/rafap/ktflag/ImplHelp.kt"
    click CommandRegister "https://github.com/rafapear/ktflag/blob/master/src/main/kotlin/pt/rafap/ktflag/cmd/CommandRegister.kt"
    click CommandImpl "https://github.com/rafapear/ktflag/blob/master/src/main/kotlin/pt/rafap/ktflag/cmd/CommandImpl.kt"
    click CommandInfo "https://github.com/rafapear/ktflag/blob/master/src/main/kotlin/pt/rafap/ktflag/cmd/CommandInfo.kt"
    click CommandResult "https://github.com/rafapear/ktflag/blob/master/src/main/kotlin/pt/rafap/ktflag/cmd/CommandResult.kt"
    click CommandResultType "https://github.com/rafapear/ktflag/blob/master/src/main/kotlin/pt/rafap/ktflag/cmd/CommandResultType.kt"
    click CommandArgsParser "https://github.com/rafapear/ktflag/blob/master/src/main/kotlin/pt/rafap/ktflag/cmd/args/CommandArgsParser.kt"
    click CommandArg "https://github.com/rafapear/ktflag/blob/master/src/main/kotlin/pt/rafap/ktflag/cmd/args/CommandArg.kt"
    click Colors "https://github.com/rafapear/ktflag/blob/master/src/main/kotlin/pt/rafap/ktflag/style/Colors.kt"

    %% Styles
    classDef core fill:#BEE3F8,stroke:#3182CE,color:#1A365D,stroke-width:1px
    classDef impl fill:#C6F6D5,stroke:#2F855A,color:#22543D,stroke-width:1px
    classDef util fill:#FEEBC8,stroke:#DD6B20,color:#7B341E,stroke-width:1px
    classDef consumer fill:#E2E8F0,stroke:#4A5568,color:#1A202C,stroke-width:1px,stroke-dasharray: 5 5
```
