How korex-labs/kmap works
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: cli.py CLI · model Model · core.py run_all · inventory Inventory
Components 21
CLI & Orchestration
User-facing commands and pipeline entrypoints.
- kmap.py · Legacy entrypoint for `python kmap.py ...`.
kmap.py - CLI · Top-level command dispatch and argument handling.
kmap/cli.py - run_all · End-to-end discovery, preflight, staged execution, and progress.
kmap/command/run_all/core.py - inspect · CLI slice for cluster inspection and observation collection.
kmap/command/inspect/cli.py - normalize · CLI slice that turns intermediate data into canonical model form.
kmap/command/normalize/cli.py - render · CLI entrypoint for rendering generated architecture artifacts.
kmap/command/render/cli.py - validate · CLI surface for config and artifact validation.
Discovery & Normalization
Kubernetes intake, inspection, and inventory shaping.
- Kubernetes · Low-level cluster access, object parsing, and metadata extraction.
kmap/kubernetes - Inspection · Turns raw Kubernetes objects into workloads, runtime facts, and dependencies.
kmap/inspection - Inventory · Organizes discovery results into cluster, namespace, repository, and bucket views.
kmap/inventory
Canonical Model
Normalized architecture model shared by renderers.
- Model · Normalized assemblies, projects, workloads, dependencies, relationships, and reports.
kmap/model - Dependencies · External/internal dependency graph and traffic flow representation.
kmap/model/dependencies - Workloads · Workload assembly, processing context, and deployment-aware normalization.
kmap/model/workloads
Rendering Outputs
Final documentation generators and file layout helpers.
- LikeC4 · Generates LikeC4 models, views, deployment views, and readmes.
kmap/render/likec4 - Structurizr · Generates Structurizr workspaces, model files, views, and deployment artifacts.
kmap/render/structurizr - Markdown · Tabular documentation output used by inventory and reports.
kmap/render/markdown
Validation & Support
Cross-cutting config, naming, logging, and path utilities.
- Config · Product and tool configuration discovery, validation, and metadata.
kmap/config - Paths · Centralized path discovery and generated output locations.
kmap/paths.py - Naming · Display names, aliases, and release/name normalization.
kmap/naming - Logging · Command logging, progress output, and lifecycle reporting.
kmap/logging - Validation · Checks config correctness and validates generated LikeC4/Structurizr artifacts.
kmap/command/validate_config
Connections 24
- 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.