# korex-labs/kmap architecture

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

- Interactive diagram: https://gitdiagram.com/korex-labs/kmap
- Repository: https://github.com/korex-labs/kmap

## Overview

1. **What this repo is**
   - `kmap` is a Python CLI pipeline that discovers Kubernetes workloads, normalizes them into an architecture model, and renders documentation for **LikeC4** and **Structurizr**.
   - The source inputs are **Kubernetes state + product config**, not an existing diagram format.

2. **Primary execution boundary**
   - The `kmap.command.*` package is the user-facing CLI surface.
   - Most commands are thin entrypoints over reusable core modules, so the architecture is centered on shared pipeline code rather than monolithic scripts.
   - `kmap.py` is a compatibility shim for `python kmap.py ...`.

3. **Configuration and filesystem layout**
   - Runtime behavior is driven by product config files under `config/` and optional tool defaults in `kmap.yaml`.
   - The repo assumes a filesystem-oriented working directory with generated roots like `LikeC4/`, `Structurizr/`, `Inventory/`, `artifacts/buckets/`, and `.tmp/`.
   - `kmap.paths` and `kmap.command.run_all.paths` centralize path discovery and output location decisions.

4. **Kubernetes adapter layer**
   - `kmap.kubernetes` is the low-level integration layer for cluster access and object interpretation.
   - It covers kubeconfig/client handling plus parsing of Kubernetes resources, metadata, scheduling, probes, security, and network objects.
   - This layer isolates raw cluster APIs from higher-level discovery logic.

5. **Inspection and normalization of cluster facts**
   - `kmap.inspection` turns raw Kubernetes objects into structured observations: workloads, runtime details, dependencies, buckets, and dependency sanitization.
   - It includes candidate detection, source parsing, env/internal dependency analysis, and deduplication.
   - Mocking and sanitization modules indicate the inspection stage is designed to support repeatable tests and controlled data generation.

6. **Inventory as an intermediate product**
   - `kmap.inventory` organizes discovered data into cluster, namespace, repository, and bucket-oriented artifacts.
   - It includes live-cluster discovery, full discovery, repository matching/enrichment, HTML/report generation, and per-namespace/cluster state tracking.
   - This layer is where discovery becomes reportable inventory, including repository metadata and bucket artifacts.

7. **Canonical model layer**
   - `kmap.model` is the normalized architecture model used by the renderers.
   - It contains assemblies, projects, workloads, deployments, dependencies, relationships, traffic flows, metadata, and reporting structures.
   - The model layer is the key boundary between discovery/inventory and output generation.

8. **Rendering outputs**
   - `kmap.render.likec4` and `kmap.render.structurizr` produce the final architecture documentation artifacts.
   - These renderers generate model files, views, deployment views, metadata, readmes, and supporting reference/content files.
   - `kmap.render.markdown` supports tabular documentation output, and `kmap.render` also handles generated-path bookkeeping.

9. **Validation and quality gates**
   - `validate_config` checks product/tool configuration correctness.
   - `validate_likec4` and `validate_structurizr` verify generated artifacts against the target tool expectations.
   - The test suite is broad and boundary-focused, reflecting the repo’s emphasis on keeping config, inspection, model, and render layers separated.

10. **Orchestration and user workflows**
   - `run_all` is the end-to-end orchestrator: discovery, preflight checks, target selection, staged execution, and progress reporting.
   - Other commands expose slices of the pipeline such as `inspect`, `combine`, `normalize`, `render_inventory`, `render_buckets`, `config_recommend`, and `view`.
   - Cross-cutting support lives in `kmap.logging`, `kmap.progress`, naming/identifier modules, and external mapping/config discovery.

Main entry points: [`kmap/cli.py`](https://github.com/korex-labs/kmap/blob/master/kmap/cli.py) (CLI), [`kmap/model`](https://github.com/korex-labs/kmap/tree/master/kmap/model) (Model), [`kmap/command/run_all/core.py`](https://github.com/korex-labs/kmap/blob/master/kmap/command/run_all/core.py) (run_all), [`kmap/inventory`](https://github.com/korex-labs/kmap/tree/master/kmap/inventory) (Inventory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI & Orchestration"]
  node_kmap_py["kmap.py<br/>compat shim<br/>[kmap.py]"]
  node_cli_main["CLI<br/>command router<br/>[cli.py]"]
  node_run_all["run_all<br/>pipeline orchestrator<br/>[core.py]"]
  node_inspect_cmd["inspect<br/>discovery command<br/>[cli.py]"]
  node_normalize_cmd["normalize<br/>model command<br/>[cli.py]"]
  node_render_cmd["render<br/>output command<br/>[cli.py]"]
  node_validate_cmd["validate<br/>quality command"]
end

subgraph group_discovery["Discovery & Normalization"]
  node_kube["Kubernetes<br/>cluster adapter"]
  node_inspection["Inspection<br/>fact extraction"]
  node_inventory["Inventory<br/>intermediate artifacts"]
end

subgraph group_model["Canonical Model"]
  node_model_core["Model"]
  node_model_deps["Dependencies<br/>model relations"]
  node_model_workloads["Workloads<br/>model processing"]
end

subgraph group_rendering["Rendering Outputs"]
  node_render_likec4["LikeC4<br/>renderer"]
  node_render_structurizr["Structurizr<br/>renderer"]
  node_render_markdown["Markdown<br/>table renderer"]
end

subgraph group_support["Validation & Support"]
  node_config["Config"]
  node_paths["Paths<br/>filesystem layout<br/>[paths.py]"]
  node_naming["Naming<br/>identifier rules"]
  node_logging["Logging<br/>runner output"]
  node_validation["Validation<br/>quality gates"]
end

node_kmap_py -->|"invoke"| node_cli_main
node_cli_main -->|"dispatch"| node_run_all
node_cli_main -->|"dispatch"| node_inspect_cmd
node_cli_main -->|"dispatch"| node_normalize_cmd
node_cli_main -->|"dispatch"| node_render_cmd
node_cli_main -->|"dispatch"| node_validate_cmd
node_run_all -->|"preflight"| node_config
node_run_all -->|"resolve"| node_paths
node_run_all -->|"discover"| node_kube
node_kube -->|"facts"| node_inspection
node_inspection -->|"shape"| node_inventory
node_inventory -->|"normalize"| node_model_core
node_model_core -->|"relations"| node_model_deps
node_model_core -->|"workloads"| node_model_workloads
node_model_core -->|"render"| node_render_likec4
node_model_core -->|"render"| node_render_structurizr
node_inventory -->|"reports"| node_render_markdown
node_config -->|"check"| node_validation
node_render_likec4 -->|"verify"| node_validation
node_render_structurizr -->|"verify"| node_validation
node_naming -->|"normalize names"| node_inspection
node_logging -->|"report"| node_run_all
node_paths -->|"outputs"| node_render_likec4
node_paths -->|"outputs"| node_render_structurizr

click node_kmap_py "https://github.com/korex-labs/kmap/blob/master/kmap.py"
click node_cli_main "https://github.com/korex-labs/kmap/blob/master/kmap/cli.py"
click node_run_all "https://github.com/korex-labs/kmap/blob/master/kmap/command/run_all/core.py"
click node_inspect_cmd "https://github.com/korex-labs/kmap/blob/master/kmap/command/inspect/cli.py"
click node_normalize_cmd "https://github.com/korex-labs/kmap/blob/master/kmap/command/normalize/cli.py"
click node_render_cmd "https://github.com/korex-labs/kmap/blob/master/kmap/command/render/cli.py"
click node_kube "https://github.com/korex-labs/kmap/tree/master/kmap/kubernetes"
click node_inspection "https://github.com/korex-labs/kmap/tree/master/kmap/inspection"
click node_inventory "https://github.com/korex-labs/kmap/tree/master/kmap/inventory"
click node_config "https://github.com/korex-labs/kmap/tree/master/kmap/config"
click node_paths "https://github.com/korex-labs/kmap/blob/master/kmap/paths.py"
click node_naming "https://github.com/korex-labs/kmap/tree/master/kmap/naming"
click node_logging "https://github.com/korex-labs/kmap/tree/master/kmap/logging"
click node_model_core "https://github.com/korex-labs/kmap/tree/master/kmap/model"
click node_model_deps "https://github.com/korex-labs/kmap/tree/master/kmap/model/dependencies"
click node_model_workloads "https://github.com/korex-labs/kmap/tree/master/kmap/model/workloads"
click node_render_likec4 "https://github.com/korex-labs/kmap/tree/master/kmap/render/likec4"
click node_render_structurizr "https://github.com/korex-labs/kmap/tree/master/kmap/render/structurizr"
click node_render_markdown "https://github.com/korex-labs/kmap/tree/master/kmap/render/markdown"
click node_validation "https://github.com/korex-labs/kmap/tree/master/kmap/command/validate_config"

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_kmap_py,node_cli_main,node_run_all,node_inspect_cmd,node_normalize_cmd,node_render_cmd,node_validate_cmd toneBlue
class node_kube,node_inspection,node_inventory toneAmber
class node_model_core,node_model_deps,node_model_workloads toneMint
class node_render_likec4,node_render_structurizr,node_render_markdown toneRose
class node_config,node_paths,node_naming,node_logging,node_validation toneIndigo
```

## Components

### CLI & Orchestration

User-facing commands and pipeline entrypoints.

- [kmap.py](https://github.com/korex-labs/kmap/blob/master/kmap.py): compat shim · Legacy entrypoint for `python kmap.py ...`. · `kmap.py`
- [CLI](https://github.com/korex-labs/kmap/blob/master/kmap/cli.py): command router · Top-level command dispatch and argument handling. · `kmap/cli.py`
- [run_all](https://github.com/korex-labs/kmap/blob/master/kmap/command/run_all/core.py): pipeline orchestrator · End-to-end discovery, preflight, staged execution, and progress. · `kmap/command/run_all/core.py`
- [inspect](https://github.com/korex-labs/kmap/blob/master/kmap/command/inspect/cli.py): discovery command · CLI slice for cluster inspection and observation collection. · `kmap/command/inspect/cli.py`
- [normalize](https://github.com/korex-labs/kmap/blob/master/kmap/command/normalize/cli.py): model command · CLI slice that turns intermediate data into canonical model form. · `kmap/command/normalize/cli.py`
- [render](https://github.com/korex-labs/kmap/blob/master/kmap/command/render/cli.py): output command · CLI entrypoint for rendering generated architecture artifacts. · `kmap/command/render/cli.py`
- **validate**: quality command · CLI surface for config and artifact validation.

### Discovery & Normalization

Kubernetes intake, inspection, and inventory shaping.

- [Kubernetes](https://github.com/korex-labs/kmap/tree/master/kmap/kubernetes): cluster adapter · Low-level cluster access, object parsing, and metadata extraction. · `kmap/kubernetes`
- [Inspection](https://github.com/korex-labs/kmap/tree/master/kmap/inspection): fact extraction · Turns raw Kubernetes objects into workloads, runtime facts, and dependencies. · `kmap/inspection`
- [Inventory](https://github.com/korex-labs/kmap/tree/master/kmap/inventory): intermediate artifacts · Organizes discovery results into cluster, namespace, repository, and bucket views. · `kmap/inventory`

### Canonical Model

Normalized architecture model shared by renderers.

- [Model](https://github.com/korex-labs/kmap/tree/master/kmap/model): canonical architecture model · Normalized assemblies, projects, workloads, dependencies, relationships, and reports. · `kmap/model`
- [Dependencies](https://github.com/korex-labs/kmap/tree/master/kmap/model/dependencies): model relations · External/internal dependency graph and traffic flow representation. · `kmap/model/dependencies`
- [Workloads](https://github.com/korex-labs/kmap/tree/master/kmap/model/workloads): model processing · Workload assembly, processing context, and deployment-aware normalization. · `kmap/model/workloads`

### Rendering Outputs

Final documentation generators and file layout helpers.

- [LikeC4](https://github.com/korex-labs/kmap/tree/master/kmap/render/likec4): renderer · Generates LikeC4 models, views, deployment views, and readmes. · `kmap/render/likec4`
- [Structurizr](https://github.com/korex-labs/kmap/tree/master/kmap/render/structurizr): renderer · Generates Structurizr workspaces, model files, views, and deployment artifacts. · `kmap/render/structurizr`
- [Markdown](https://github.com/korex-labs/kmap/tree/master/kmap/render/markdown): table renderer · Tabular documentation output used by inventory and reports. · `kmap/render/markdown`

### Validation & Support

Cross-cutting config, naming, logging, and path utilities.

- [Config](https://github.com/korex-labs/kmap/tree/master/kmap/config): product config · Product and tool configuration discovery, validation, and metadata. · `kmap/config`
- [Paths](https://github.com/korex-labs/kmap/blob/master/kmap/paths.py): filesystem layout · Centralized path discovery and generated output locations. · `kmap/paths.py`
- [Naming](https://github.com/korex-labs/kmap/tree/master/kmap/naming): identifier rules · Display names, aliases, and release/name normalization. · `kmap/naming`
- [Logging](https://github.com/korex-labs/kmap/tree/master/kmap/logging): runner output · Command logging, progress output, and lifecycle reporting. · `kmap/logging`
- [Validation](https://github.com/korex-labs/kmap/tree/master/kmap/command/validate_config): quality gates · Checks config correctness and validates generated LikeC4/Structurizr artifacts. · `kmap/command/validate_config`

## Connections

- kmap.py → CLI: invoke · Compatibility shim forwards into the main CLI router.
- CLI → run_all: dispatch · Routes the end-to-end workflow command.
- CLI → inspect: dispatch · Routes inspection-focused commands.
- CLI → normalize: dispatch · Routes normalization commands.
- CLI → render: dispatch · Routes rendering commands.
- CLI → validate: dispatch · Routes validation commands.
- run_all → Config: preflight · Loads product/tool config and validates execution settings.
- run_all → Paths: resolve · Determines working directories and output roots.
- run_all → Kubernetes: discover · Starts cluster discovery from live Kubernetes sources.
- Kubernetes → Inspection: facts · Raw objects feed inspection and sanitization.
- Inspection → Inventory: shape · Structured observations become inventory artifacts.
- Inventory → Model: normalize · Inventory is consolidated into the canonical model.
- Model → Dependencies: relations · Dependency structures are separated into dedicated model components.
- Model → Workloads: workloads · Workload processing is a core part of model construction.
- Model → LikeC4: render · LikeC4 consumes the canonical model.
- Model → Structurizr: render · Structurizr consumes the canonical model.
- Inventory → Markdown: reports · Inventory outputs tabular documentation and summaries.
- Config → Validation: check · Configuration is verified by validation commands and tool gates.
- LikeC4 → Validation: verify · Generated LikeC4 artifacts are validated against tool expectations.
- Structurizr → Validation: verify · Generated Structurizr artifacts are validated against tool expectations.
- Naming → Inspection: normalize names · Name rules help cluster facts collapse into stable entities.
- Logging → run_all: report · Orchestration uses structured progress and command logging.
- Paths → LikeC4: outputs · Generated path helpers direct renderer destinations.
- Paths → Structurizr: outputs · Generated path helpers direct renderer destinations.