# knadh/koanf architecture

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

- Interactive diagram: https://gitdiagram.com/knadh/koanf
- Repository: https://github.com/knadh/koanf

## Overview

koanf is a Go configuration-loading library: applications combine providers for sources with parsers for formats, load and merge the resulting values, then query or marshal configuration. Its documented capabilities include files, flags, environment variables, cloud and remote stores, maps/structs, file watching, custom extensions, and multiple serialization formats. Core loading and map behavior are visible in the source index; several provider and parser relationships are documented in the README, while many provider implementations were not sampled.

Main entry points: [`koanf.go`](https://github.com/knadh/koanf/blob/master/koanf.go) (Koanf loader), [`maps/maps.go`](https://github.com/knadh/koanf/blob/master/maps/maps.go) (Nested map utilities), [`providers/env/env.go`](https://github.com/knadh/koanf/blob/master/providers/env/env.go) (Environment variables), [`providers/posflag/posflag.go`](https://github.com/knadh/koanf/blob/master/providers/posflag/posflag.go) (Command-line flags)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core configuration"]
  node_koanf["Koanf loader<br/>[koanf.go]"]
  node_getters["Config getters<br/>[getters.go]"]
  node_interfaces["Provider and parser APIs<br/>[interfaces.go]"]
  node_maps["Nested map utilities<br/>[maps.go]"]
  node_options["Load options<br/>[options.go]"]
end

subgraph group_providers["Configuration providers"]
  node_file["File and filesystem"]
  node_environment["Environment variables<br/>[env.go]"]
  node_flags["Command-line flags<br/>[posflag.go]"]
  node_memory["Maps, structs, bytes"]
  node_kubernetes["Kubernetes mounts<br/>[provider.go]"]
end

subgraph group_parsers["Format parsers"]
  node_parsers["Format parsers"]
  node_json["JSON parser<br/>[json.go]"]
  node_yaml["YAML parser<br/>[yaml.go]"]
  node_toml["TOML parser<br/>[toml.go]"]
  node_dotenv["DOTENV parser<br/>[dotenv.go]"]
  node_otherformats["Other parsers"]
end

subgraph group_stores["Remote stores"]
  node_cloud["Cloud configuration"]
  node_consul["Consul and etcd"]
  node_nats["NATS key-value<br/>[nats.go]"]
end

node_application(("Go application"))

node_application -->|"loads config"| node_koanf
node_koanf -->|"reads provider"| node_file
node_koanf -->|"reads provider"| node_environment
node_koanf -->|"reads provider"| node_flags
node_koanf -->|"reads provider"| node_memory
node_koanf -.->|"reads provider"| node_kubernetes
node_koanf -->|"reads provider"| node_cloud
node_koanf -->|"reads provider"| node_consul
node_koanf -.->|"reads provider"| node_nats
node_koanf -->|"parses with"| node_json
node_koanf -->|"parses with"| node_yaml
node_koanf -->|"parses with"| node_toml
node_koanf -->|"parses with"| node_dotenv
node_koanf -->|"parses with"| node_otherformats
node_koanf -->|"uses maps"| node_maps
node_application -->|"queries values"| node_getters
node_koanf -->|"exposes values"| node_getters
node_interfaces -.->|"defines contracts"| node_koanf
node_options -.->|"configures loading"| node_koanf
node_environment -->|"unflattens keys"| node_maps
node_flags -->|"unflattens keys"| node_maps
node_dotenv -->|"unflattens keys"| node_maps
node_nats -->|"unflattens keys"| node_maps

click node_koanf "https://github.com/knadh/koanf/blob/master/koanf.go"
click node_getters "https://github.com/knadh/koanf/blob/master/getters.go"
click node_interfaces "https://github.com/knadh/koanf/blob/master/interfaces.go"
click node_maps "https://github.com/knadh/koanf/blob/master/maps/maps.go"
click node_options "https://github.com/knadh/koanf/blob/master/options.go"
click node_file "https://github.com/knadh/koanf/tree/master/providers/file"
click node_environment "https://github.com/knadh/koanf/blob/master/providers/env/env.go"
click node_flags "https://github.com/knadh/koanf/blob/master/providers/posflag/posflag.go"
click node_memory "https://github.com/knadh/koanf/tree/master/providers"
click node_kubernetes "https://github.com/knadh/koanf/blob/master/providers/k8smount/provider.go"
click node_cloud "https://github.com/knadh/koanf/tree/master/providers"
click node_consul "https://github.com/knadh/koanf/tree/master/providers"
click node_nats "https://github.com/knadh/koanf/blob/master/providers/nats/nats.go"
click node_parsers "https://github.com/knadh/koanf/tree/master/parsers"
click node_json "https://github.com/knadh/koanf/blob/master/parsers/json/json.go"
click node_yaml "https://github.com/knadh/koanf/blob/master/parsers/yaml/yaml.go"
click node_toml "https://github.com/knadh/koanf/blob/master/parsers/toml/toml.go"
click node_dotenv "https://github.com/knadh/koanf/blob/master/parsers/dotenv/dotenv.go"
click node_otherformats "https://github.com/knadh/koanf/tree/master/parsers"

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_koanf,node_getters,node_interfaces,node_maps,node_options toneBlue
class node_file,node_environment,node_flags,node_memory,node_kubernetes toneAmber
class node_parsers,node_json,node_yaml,node_toml,node_dotenv,node_otherformats toneMint
class node_cloud,node_consul,node_nats toneRose
class node_application toneIndigo
```

## Components

### Core configuration

- [Koanf loader](https://github.com/knadh/koanf/blob/master/koanf.go): `koanf.go`
- [Config getters](https://github.com/knadh/koanf/blob/master/getters.go): `getters.go`
- [Provider and parser APIs](https://github.com/knadh/koanf/blob/master/interfaces.go): `interfaces.go`
- [Nested map utilities](https://github.com/knadh/koanf/blob/master/maps/maps.go): `maps/maps.go`
- [Load options](https://github.com/knadh/koanf/blob/master/options.go): `options.go`

### Configuration providers

- [File and filesystem](https://github.com/knadh/koanf/tree/master/providers/file): `providers/file`
- [Environment variables](https://github.com/knadh/koanf/blob/master/providers/env/env.go): `providers/env/env.go`
- [Command-line flags](https://github.com/knadh/koanf/blob/master/providers/posflag/posflag.go): `providers/posflag/posflag.go`
- [Maps, structs, bytes](https://github.com/knadh/koanf/tree/master/providers): `providers`
- [Kubernetes mounts](https://github.com/knadh/koanf/blob/master/providers/k8smount/provider.go): `providers/k8smount/provider.go`

### Format parsers

- [Format parsers](https://github.com/knadh/koanf/tree/master/parsers): `parsers`
- [JSON parser](https://github.com/knadh/koanf/blob/master/parsers/json/json.go): `parsers/json/json.go`
- [YAML parser](https://github.com/knadh/koanf/blob/master/parsers/yaml/yaml.go): `parsers/yaml/yaml.go`
- [TOML parser](https://github.com/knadh/koanf/blob/master/parsers/toml/toml.go): `parsers/toml/toml.go`
- [DOTENV parser](https://github.com/knadh/koanf/blob/master/parsers/dotenv/dotenv.go): `parsers/dotenv/dotenv.go`
- [Other parsers](https://github.com/knadh/koanf/tree/master/parsers): `parsers`

### Remote stores

- [Cloud configuration](https://github.com/knadh/koanf/tree/master/providers): `providers`
- [Consul and etcd](https://github.com/knadh/koanf/tree/master/providers): `providers`
- [NATS key-value](https://github.com/knadh/koanf/blob/master/providers/nats/nats.go): `providers/nats/nats.go`

### Other components

- **Go application**

## Connections

- Go application → Koanf loader: loads config
- Koanf loader → File and filesystem: reads provider
- Koanf loader → Environment variables: reads provider
- Koanf loader → Command-line flags: reads provider
- Koanf loader → Maps, structs, bytes: reads provider
- Koanf loader → Kubernetes mounts: reads provider
- Koanf loader → Cloud configuration: reads provider
- Koanf loader → Consul and etcd: reads provider
- Koanf loader → NATS key-value: reads provider
- Koanf loader → JSON parser: parses with
- Koanf loader → YAML parser: parses with
- Koanf loader → TOML parser: parses with
- Koanf loader → DOTENV parser: parses with
- Koanf loader → Other parsers: parses with
- Koanf loader → Nested map utilities: uses maps (evidence: `koanf.go`)
- Go application → Config getters: queries values
- Koanf loader → Config getters: exposes values
- Provider and parser APIs → Koanf loader: defines contracts
- Load options → Koanf loader: configures loading
- Environment variables → Nested map utilities: unflattens keys (evidence: `providers/env/env.go`)
- Command-line flags → Nested map utilities: unflattens keys (evidence: `providers/posflag/posflag.go`)
- DOTENV parser → Nested map utilities: unflattens keys (evidence: `parsers/dotenv/dotenv.go`)
- NATS key-value → Nested map utilities: unflattens keys (evidence: `providers/nats/nats.go`)
