ConfigKit/docs/internal/overview.md

Internal Component Overview

ConfigKit exposes the root configkit package and keeps its document and YAML representations private. The implemented components and their owners are:

• immutable semantic Path construction and strict JSON Pointer parsing;
• detached effective presence/origin and chronological history queries in metadata.go, with provenance and diagnostic record types;
• canonical, control-safe diagnostic rendering and structured LoadError access;
• opaque file, byte, reader, and no-input source construction in source.go, with shared regular-file checks and bounded read mechanics in source_file.go;
• a parser-independent ordered tree in internal/document, with root-private semantic lookup, indexing, and value traversal in document_walk.go;
• the sole upstream YAML integration in internal/yaml, which translates validated input into that owned tree and exposes no parser types outside its boundary; parse.go owns shared translation into detached, ordered public diagnostics;
• a private strict composer in compose.go that joins only disjoint document-tree definitions, retains ordered claims and composite mapping origins, reports every conflicting location, and never aliases an input tree;
• fixed selected-profile loading in profile.go and recursive, non-aliasing overlay with displacement records in overlay.go; overlay records retain origins, while value explanation uses separate history applications;
• CLI override validation/preparation in override.go, parser-neutral values in override_value.go, and synthetic-source application in override_apply.go, sharing overlay, source, byte, node, and depth policies;
• a per-operation private reflection descriptor graph in schema.go for supported types, YAML field binding, inlining, secret tags, recursion, and semantic paths;
• descriptor-driven canonical projection in projection.go, detached typed cloning with explicit secret-state modes in clone.go, shared reflection and cycle/limit state in value_operation.go, and configuration-value comparison in document_compare.go; validation separately audits sensitivity and secrets;
• strict schema-driven decoding over detached defaults in decode.go, including mapping/sequence semantics, null and numeric policy, safe codec errors, presence, baseline/final trees, and initial default/input origins;
• public lifecycle coordination in load.go, option selection in options.go, input assembly in load_input.go, typed phases/publication in load_result.go, bounded canonical import DFS in imports.go, filesystem context/containment in filesystem.go, directive parsing/restrictions in directives.go, pattern-directed glob expansion in glob.go, schema-version checking and report contexts in validation.go, and layered metadata/history assembly in load_metadata.go;
• recorded application defaulting and normalization in resolution.go, including callback-scoped fixed entry metadata/source queries, explicitness queries, helper verification, structural mutation audit, coalesced intent, private before/after snapshots, and resolution metadata integration;
• post-resolution schema-aware report collection and validator mutation detection in validation.go, completing the public callback lifecycle after composed input;
• opaque typed environment references and per-load name resolution in secret_reference.go, including credential-free projection/cloning and private validator-state auditing;
• explicit bounded startup environment bootstrap and safe partial reporting in secrets.go;
• fixed-point tag/predicate/dependency sensitivity classification in secret.go;
• canonical effective output in render.go, using frozen-snapshot redaction shared with explanation in snapshot.go;
• detached public explanation records and coordination in explain.go, immutable input applications/replay and retained-node budgeting in history.go, shared safe snapshot projection in snapshot.go, and deterministic human output in explain_render.go; the only upstream dumper integration remains isolated in internal/yaml/write.go;
• a separate maintained examples/consumers package with four sanitized consumer shapes, fixtures, domain validators, and runtime-boundary functions; and
• an everyday single-toolchain check in scripts/check.sh and a stricter source-candidate checker in scripts/release-check.sh, with local documentation-link and public import-boundary gates owned by root-package tests.

Dependency direction remains inward: the public lifecycle coordinates private source, document, schema, and inspection helpers. Semantic paths stay in the root package; internal/document owns only representation and cloning and never imports the root package. Only internal/yaml imports the upstream YAML package. Maintained consumer examples use the public package and standard library.

The configuration contract owns implemented input, schema, decoding, loading lifecycle, path imports, composition, profile/CLI overlay, version checking, recorded resolution, typed secret references/bootstrap, semantic validation, metadata, secret classification, redacted effective rendering, historical explanation, and ownership behavior. The consumer adoption guide owns current application-fit and migration guidance.

The source-extraction inventory records the application foundations used by the implementation:

• Extraction inventory

The architecture policy owns binding boundaries and invariants. The deferred scope records deliberate exclusions. See the development guide for contributor orientation and validation and the release procedure for source-candidate gates.