142 lines
6.0 KiB
Markdown
142 lines
6.0 KiB
Markdown
# Architecture Policy
|
|
|
|
## Purpose
|
|
|
|
This document defines Promptkit's current high-level architecture and the
|
|
durable boundaries that implementation changes must preserve. The
|
|
[internal component overview](../internal/overview.md) inventories concrete
|
|
implemented packages without redefining these rules.
|
|
|
|
## System Shape
|
|
|
|
Promptkit is an importable Go library. It does not provide a runnable command,
|
|
an HTTP service, or another application process.
|
|
|
|
The module root contains package `promptkit`, which is the public facade. It
|
|
declares the module's public package boundary but does not yet provide a usable
|
|
exported framework API.
|
|
|
|
The implemented internal components consist of:
|
|
|
|
- `internal/domain`, which owns framework data values shared by later internal
|
|
components;
|
|
- `internal/defaults`, which owns application-neutral framework defaults and
|
|
constructs the default execution target; and
|
|
- `internal/filecatalog`, which discovers YAML files and provides source-path
|
|
helpers for filesystem and `fs.FS` consumers;
|
|
- `internal/promptdef`, which loads and validates prompt definitions from
|
|
filesystem and `fs.FS` sources;
|
|
- `internal/profile`, which loads, validates, and overlays execution profiles
|
|
from filesystem and `fs.FS` sources;
|
|
- `internal/profile/builtin`, which embeds the built-in execution profile
|
|
catalog; and
|
|
- `internal/prompt`, which renders prompt messages from Go templates.
|
|
|
|
The defaults and renderer depend on the domain model. Prompt-definition and
|
|
profile repositories use the domain model, file catalog, and YAML decoder. The
|
|
built-in profile repository supplies an embedded `fs.FS` to the profile
|
|
package. Artifact reading, output validation, model clients, orchestration, and
|
|
the public engine have not yet been extracted.
|
|
|
|
Future framework extraction must follow this dependency direction:
|
|
|
|
```text
|
|
downstream consumers, including Scriptorium
|
|
|
|
|
v
|
|
root promptkit public facade
|
|
|
|
|
v
|
|
internal framework components
|
|
|
|
|
v
|
|
narrow injected abstractions
|
|
```
|
|
|
|
The facade may coordinate internal components once the public engine is
|
|
extracted. Internal components must depend on narrow abstractions for behavior
|
|
supplied from outside the library; they must not depend on consumers or on
|
|
Scriptorium. This diagram is the target dependency direction for later
|
|
extraction and does not assert that the public facade already assembles the
|
|
implemented foundation.
|
|
|
|
## Repository And Consumer Boundary
|
|
|
|
Scriptorium is a downstream application that will consume Promptkit through
|
|
the supported public facade. It is not a Promptkit package and must not become
|
|
an internal dependency.
|
|
|
|
Promptkit owns reusable, application-neutral library behavior. It does not own:
|
|
|
|
- binaries or executable packaging;
|
|
- CLI commands, parsing, streams, or exit codes;
|
|
- HTTP routes, servers, request DTOs, status mapping, or deployment policy;
|
|
- application configuration discovery or precedence;
|
|
- process lifecycle, operational state, or application logging; or
|
|
- consumer-specific filesystem or security policy.
|
|
|
|
Those concerns remain with Scriptorium or another consuming application.
|
|
|
|
## Package Ownership
|
|
|
|
The module root is the supported public facade. Framework implementation
|
|
packages belong under Go's `internal/` boundary unless a demonstrated, stable
|
|
consumer contract requires a public package.
|
|
|
|
Each package must have one cohesive responsibility and a clear dependency
|
|
direction. Internal packages must not expose their types merely to simplify
|
|
wiring, and the public facade must not leak internal representations through
|
|
exported signatures. New public packages require a durable consumer need that
|
|
cannot be served cleanly by the root facade.
|
|
|
|
The [internal component overview](../internal/overview.md) must be updated as
|
|
packages are implemented or their responsibilities change.
|
|
|
|
## Exported API Discipline
|
|
|
|
Export the smallest contract required by real consumers. Exported declarations
|
|
must have accurate GoDoc, stable semantics, and tests proportionate to their
|
|
compatibility risk. Avoid speculative extension points, aliases for internal
|
|
types, and public constructors that expose assembly details.
|
|
|
|
Once an exported API exists, its Go declaration and GoDoc own its exact public
|
|
contract. Architecture documentation owns boundary rules, not a duplicate API
|
|
reference.
|
|
|
|
## Error Boundaries
|
|
|
|
Internal failures must cross the public facade as errors meaningful to a Go
|
|
consumer without exposing private package types or transport-specific policy.
|
|
Wrapping should add useful context while preserving any public error identity
|
|
needed with `errors.Is` or `errors.As`.
|
|
|
|
Promptkit must not assign CLI exit codes or HTTP status codes. Consumers map
|
|
public library outcomes into their own transport behavior.
|
|
|
|
## Dependency Injection
|
|
|
|
External effects and consumer-selected policy must enter through narrow
|
|
interfaces or functions at the boundary that uses them. Dependencies should be
|
|
explicitly supplied during construction or invocation rather than read from
|
|
consumer configuration or hidden process-global state.
|
|
|
|
Interfaces should be owned by the code that consumes the behavior and should
|
|
contain only the operations that code requires. Provide defaults only for
|
|
application-neutral behavior; consumer-specific restrictions and adapters
|
|
remain injected from the consuming project.
|
|
|
|
## Repository Independence
|
|
|
|
Promptkit must build, test, and validate independently of Scriptorium. Do not
|
|
commit `go.work`, `go.work.sum`, or a local filesystem `replace` directive.
|
|
Temporary workspace or replacement configuration may support coordinated local
|
|
development, but it is not part of either repository's architecture or release
|
|
state.
|
|
|
|
## Current-State Maintenance
|
|
|
|
This policy distinguishes present implementation from constraints on future
|
|
framework extraction. Do not list planned packages as implemented components.
|
|
When extraction introduces a package, update the internal inventory and the
|
|
owning contract or subsystem document in the same change.
|