Architecture

This document defines Scriptorium's current application architecture and durable development boundaries.

System Shape

Scriptorium is an executable application with three entry paths: CLI run, CLI render, and the HTTP service started by serve. It does not expose a reusable root Go package.

The application consumes Promptkit v0.1.0 through its supported root package. Promptkit owns prompt execution, preparation, source formats, built-in profiles, model-client behavior, and validation. Scriptorium owns application configuration, executable adapters, prepared-run presentation, process behavior, and HTTP deployment policy.

The concrete package inventory is maintained in the internal overview.

Dependency Direction

cmd/scriptorium
        |
        v
CLI and HTTP adapters, configuration, defaults, and formatting
        |
        v
gitea.maximumdirect.net/eric/promptkit

Retained application packages may import Promptkit's root package.
They must not import Promptkit internal packages.
They must not import the removed Scriptorium root facade or recreate former framework package families.
Adapter-owned interfaces use Promptkit public values when a consumer-side substitution boundary is needed.
Scriptorium passes omitted framework settings as zero values so Promptkit applies its own defaults.

The repository architecture guard enforces these import and removal invariants.

Retained Boundaries

internal/adapter/cli owns commands, flags, configuration precedence, process streams, output files, summaries, and exit codes.
internal/adapter/http owns routes, strict JSON DTOs, size limits, response mapping, status mapping, and the restricted artifact reader.
internal/config owns discovery and strict decoding of Scriptorium application configuration.
internal/defaults owns Scriptorium application and HTTP defaults only.
internal/format owns deterministic prepared-run text and JSON presentation.
Promptkit owns framework orchestration and contracts. Its format reference and outbound integration contract are canonical.

HTTP Artifact Security Boundary

Ordinary CLI file loading is provided by Promptkit. Scriptorium's HTTP adapter injects a restricted promptkit.ArtifactReader for inbound HTTP requests. That reader denies file references without an artifact root, enforces the configured byte limit, and applies Scriptorium's lexical root-containment rule. The operating system still follows symlinks after the lexical check.

The HTTP API owns observable request outcomes, and operations owns deployment permissions and root selection.

State, Errors, And Secrets

Scriptorium has no durable run-state store, checkpoint, cache, or resume mechanism. Recovery is a new request after correcting inputs, configuration, or environment.

Adapters map Promptkit public error identities into CLI exits or HTTP statuses without classifying by message text. Raw API keys are not accepted in Scriptorium configuration, CLI arguments, or HTTP payloads, and resolved secrets must not be emitted.

Architectural Invariants

External YAML and JSON decoding remains strict.
CLI and HTTP behavior remains presentation and transport logic rather than framework orchestration.
Explicit numeric request overrides preserve presence, including zero.
HTTP artifact containment and byte limits remain Scriptorium policy.
No application package depends on Promptkit implementation packages.

Non-Goals

Do not recreate an in-process Scriptorium framework API or compatibility facade.
Do not copy Promptkit types, defaults, built-in profiles, or implementation into Scriptorium.
Do not move CLI, inbound HTTP, process, or deployment policy into Promptkit.
Do not add durable workflow, archive, or resume behavior.

Work that is not implemented belongs in docs/roadmap/.

4.2 KiB Raw Blame History