# projectdiscovery/goflags architecture

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

- Interactive diagram: https://gitdiagram.com/projectdiscovery/goflags
- Repository: https://github.com/projectdiscovery/goflags

## Overview

##### Project Type and Purpose
- Project Type: An open‑source Go library extending the standard flag package.
- Purpose: Provide convenience functions, custom flag types (slices, maps, enums, callbacks), YAML config support, grouped flags, and improved usage output.

##### File Structure
- Root files: various `*_var.go` files implement each custom flag type (e.g., `string_slice.go`, `enum_var.go`, `callback_var.go`).
- `goflags.go`: central entrypoint defining `NewFlagSet`, core structs, and high‑level methods (`Parse`, `MergeConfigFile`, `CreateGroup`).
- `examples/`: a sample client demonstrating typical integration flow.
- Tests in each `*_test.go` validate type behavior.
- `ports_data.json`: static data used by `PortVar`.
- No external services, no frontend/backend split.

##### Core Components
- Imports `github.com/projectdiscovery/goflags`
- Calls `NewFlagSet()`
- Registers flags (BoolVar, StringSliceVarP, EnumVarP, CallbackVar, etc.)
- Optionally calls `MergeConfigFile()`
- Calls `Parse()`
A. FlagSet Manager
– Backed by Go’s `flag.FlagSet`
– Methods: `NewFlagSet()`, `Parse()`, `MergeConfigFile()`, `CreateGroup()`, `SetDescription()`
B. Config Loader
– YAML reading & merging into existing flags
C. Custom Variable Types
– StringSlice types (comma‑sep, normalized, file‑based)
– RuntimeMap (map[string]string)
– Enum types
– CallbackVar
– PortVar (uses `ports_data.json`)
– SizeVar, DurationVar, BoolVar, IntVar
D. Usage Template
– Improves on standard usage text (leverages spf13/cobra templates)
- Standard Library Dependency
– `flag` package
- External Assets
– `ports_data.json`
– (Optional) `github.com/spf13/cobra` for templates

##### Relationships and Interactions
- The Client calls into the FlagSet Manager to register flags.
- Each registration ties a variable pointer to a custom Var implementation.
- On `Parse()`, FlagSet iterates registered flags, invoking the underlying `flag` parse logic.
- If a config file is provided, the Config Loader reads YAML, maps keys to flags, and re‐invokes each Var’s `Set()` method.
- After parsing, the client reads the populated variables.

##### Architectural Patterns and Design Principles
- Dependency Injection: client provides pointers to its own variables.
- Strategy Pattern: each custom Var type implements the `flag.Value` interface.
- Single Responsibility: separate files and types for each Var; one module for config merging.
- Extensibility: new Var types can be added by implementing `flag.Value`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Application"
        Client["Client Application"]:::client
    end

    subgraph "goflags Library"
        subgraph "Core Modules"
            FlagSet["FlagSet Manager"]:::core
            ConfigLoader["Config Loader"]:::core
            Usage["Usage Template"]:::core
        end
        subgraph "Custom Var Types"
            Callback["CallbackVar"]:::var
            Duration["DurationVar"]:::var
            Dynamic["DynamicVar"]:::var
            Enum["EnumVar"]:::var
            EnumSlice["EnumSliceVar"]:::var
            Port["PortVar"]:::var
            RateLimit["RateLimitVar"]:::var
            RuntimeMap["RuntimeMap"]:::var
            Size["SizeVar"]:::var
            StringSlice["StringSliceVar"]:::var
        end
    end

    subgraph "External Dependencies"
        StdFlag["Go flag package"]:::external
        Cobra["spf13/cobra (templates)"]:::external
        PortsData["ports_data.json"]:::external
    end

    subgraph "Test Suite"
        CallbackT["callback_var_test.go"]:::test
        DurationT["duration_var_test.go"]:::test
        DynamicT["dynamic_var_test.go"]:::test
        EnumT["enum_var_test.go"]:::test
        EnumSliceT["enum_slice_var_test.go"]:::test
        PortT["port_test.go"]:::test
        RateLimitT["ratelimit_var_test.go"]:::test
        RuntimeMapT["runtime_map_test.go"]:::test
        SizeT["size_var_test.go"]:::test
        StringSliceT["string_slice_test.go"]:::test
    end

    Client -->|"imports & NewFlagSet()"| FlagSet
    Client -->|"register flags"| FlagSet
    Client -->|"Parse()/MergeConfigFile()"| FlagSet

    FlagSet -->|"uses"| StdFlag
    FlagSet -->|"calls"| ConfigLoader
    ConfigLoader -->|"reads YAML & Set()"| FlagSet
    FlagSet -->|"outputs usage"| Usage

    FlagSet --> Callback
    FlagSet --> Duration
    FlagSet --> Dynamic
    FlagSet --> Enum
    FlagSet --> EnumSlice
    FlagSet --> Port
    FlagSet --> RateLimit
    FlagSet --> RuntimeMap
    FlagSet --> Size
    FlagSet --> StringSlice

    Port -->|"reads"| PortsData
    Usage -->|"leverages"| Cobra

    CallbackT --> Callback
    DurationT --> Duration
    DynamicT --> Dynamic
    EnumT --> Enum
    EnumSliceT --> EnumSlice
    PortT --> Port
    RateLimitT --> RateLimit
    RuntimeMapT --> RuntimeMap
    SizeT --> Size
    StringSliceT --> StringSlice

    click Client "https://github.com/projectdiscovery/goflags/blob/main/examples/basic/main.go"
    click FlagSet "https://github.com/projectdiscovery/goflags/blob/main/goflags.go"
    click ConfigLoader "https://github.com/projectdiscovery/goflags/blob/main/goflags.go"
    click Callback "https://github.com/projectdiscovery/goflags/blob/main/callback_var.go"
    click Duration "https://github.com/projectdiscovery/goflags/blob/main/duration_var.go"
    click Dynamic "https://github.com/projectdiscovery/goflags/blob/main/dynamic_var.go"
    click Enum "https://github.com/projectdiscovery/goflags/blob/main/enum_var.go"
    click EnumSlice "https://github.com/projectdiscovery/goflags/blob/main/enum_slice_var.go"
    click Port "https://github.com/projectdiscovery/goflags/blob/main/port.go"
    click RateLimit "https://github.com/projectdiscovery/goflags/blob/main/ratelimit_var.go"
    click RuntimeMap "https://github.com/projectdiscovery/goflags/blob/main/runtime_map.go"
    click Size "https://github.com/projectdiscovery/goflags/blob/main/size_var.go"
    click StringSlice "https://github.com/projectdiscovery/goflags/blob/main/string_slice.go"
    click PortsData "https://github.com/projectdiscovery/goflags/blob/main/ports_data.json"

    classDef client fill:#D0E8FF,stroke:#0284C7,color:#03396c
    classDef core fill:#D4F4DD,stroke:#059669,color:#065F46
    classDef var fill:#FFECCF,stroke:#F97316,color:#9A3412
    classDef external fill:#E5E7EB,stroke:#6B7280,color:#374151
    classDef test fill:#F3E8FF,stroke:#8B5CF6,color:#5B21B6
```
