promptkit/docs/internal/overview.md

Internal Component Overview

Purpose

This document inventories Promptkit's implemented components for contributors. The architecture policy owns durable boundary and dependency rules. See the development guide for contributor workflow and validation.

Implemented Components

Component	Implemented responsibility	References
Root promptkit package	Provides the supported engine facade, source, backend-registration, and injection options, public request, result, prompt-inspection, and profile-inspection values, opaque prepared-execution handles, profile construction, extension interfaces, value conversion, redacted formatting, typed capacity errors, public error mapping, and engine-local profile-source assembly including application fallbacks.	Package GoDoc, prepared execution, backend API, engine assembly
examples/go-library/prepare	Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, and Prepare. It is not a public library package.	Example program
examples/go-library/run	Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, an injected deterministic model client, and Run. It is not a public library package.	Example program
internal/backend	Constructs each engine's immutable registry from the built-in OpenRouter definition and consumer additions, validates and defensively copies definitions through the shared JSON-value package, and consumes the LLM-owned OpenAI-compatible reserved request-field rule.	Backend registry
internal/capacity	Owns engine-local bounded execution admission and FIFO model-generation permits for limited backend IDs, including cancellation-safe waiter removal and client wrapping.	Internal capacity management
internal/domain	Defines internal framework values for requests, artifacts, prompt definitions, profiles, execution targets, rendering, generation, and validation, and owns source-neutral invariants for shared execution settings, session identifiers, and output contracts. Source parsing, required fields, source-specific normalization and defaulting, and boundary-specific error classification remain with their callers.	Domain declarations
internal/defaults	Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits.	Framework defaults
internal/filecatalog	Provides deterministic YAML discovery and path helpers for operating-system filesystems and fs.FS sources.	File catalog
internal/jsonvalue	Validates and deeply copies bounded JSON-compatible extra-parameter and prepared-schema trees while preserving supported concrete value types and rejecting cycles or excessive depth and work.	JSON values
internal/promptdef	Loads strictly decoded, validated prompt definitions from filesystem and fs.FS sources, including version selection and contained file-backed message content.	Framework formats, prompt-definition repository
internal/profile	Loads strictly decoded, validated execution profiles, including backend selection, from filesystem and fs.FS sources and composes repositories with error-preserving fallback.	Framework formats, profile repositories
internal/profile/builtin	Embeds the built-in profile catalog, whose entries select OpenRouter.	Built-in catalog, repository
internal/prompt	Renders prompt messages from Go templates with artifact, variable, session, and cache-control data.	Go-template renderer
internal/artifact	Resolves ordinary inline and unrestricted caller-selected file references into copied artifacts with metadata and hashes.	Internal sources and validation
internal/validate	Validates basic, JSON, and JSON Schema output using operating-system filesystem or fs.FS schema sources and creates frozen validation plans for prepared execution.	Framework formats, internal sources and validation
internal/llm	Defines the internal generation boundary and implements outbound OpenAI-compatible chat requests from resolved execution targets, including response decoding, authentication, deadline handling, and ownership of the OpenAI-compatible reserved request-field policy.	Internal model client
internal/usecase	Resolves prompt definitions and hashes, profiles, backends, and targets for exact inspection and request settings for preparation, and coordinates ordinary execution and one-attempt prepared execution across internal sources, rendering, artifact loading, generation, validation, capacity, and optional repair.	Internal runner, prepared-execution implementation

The root package assembles these internal components without exposing their representations. Consumers depend only on the root facade.

Maintenance

Update this inventory as implementation adds packages or changes component responsibilities. List only implemented components; proposed package boundaries belong in temporary planning documents until their implementation lands.