Architecture

This document is the development architecture policy for Scriptorium.

It is for developers and LLM coding agents. User-facing behavior belongs in README.md and the docs under docs/ that target operators/users.

System Shape

Scriptorium is a narrow prompt-execution application with three executable entry paths: CLI run, CLI render, and the HTTP service started by serve. It also provides a public Go package for in-process use. Executable adapters consume framework behavior through that public facade; the facade continues to compose the framework implementation inside this single repository. Its current component inventory is maintained in the internal overview.

Domain behavior is centralized in internal/usecase and internal/domain.

Core Principles

Keep orchestration narrow: Scriptorium executes one prompt request; it is not a multi-step workflow engine.
Keep adapter logic thin: adapters map external shapes to public engine requests/results and should not hold framework decisions.
Keep boundaries explicit: repositories/loaders/renderers/validators/LLM client stay behind package interfaces.
Keep external decoding strict: configuration, prompt, and profile YAML and HTTP JSON should reject unknown fields.
Keep secrets out of payloads: raw API key values must not be accepted or emitted.

Dependency Direction

Adapters translate external shapes and IO concerns; they do not make use-case decisions.
Executable adapters and prepared-run formatting use the public facade for framework behavior rather than importing framework implementation packages directly.
Use-case and domain code depend on explicit repository, renderer, validator, and LLM interfaces rather than adapter implementations.
Source, rendering, validation, and LLM implementations remain behind their package boundaries.
Dependency-specific types must not leak across unrelated package boundaries.
Prefer the standard library; add an external dependency only when it materially reduces risk or complexity.

State And Persistence Policy

Scriptorium has no durable run-state store.

No built-in resume/checkpoint/archive behavior.
Recovery model is rerun after correcting inputs/config/environment.

Contract Ownership

The CLI, configuration, HTTP API, public Go package, and integration documents own their respective external contracts. This policy keeps only the architectural boundaries that govern their implementation.

Error Handling And Logging

Wrap errors with domain/operation context.
Map public error identities to adapter-appropriate statuses/codes without leaking sensitive internals.
Never emit raw secret values.

Testing And Documentation

Testing philosophy and change-validation expectations are defined by the testing policy. Documentation ownership and maintenance rules are defined by the documentation policy.

Architectural Invariants

Runner.Run reuses Runner.Prepare flow.
Raw API key values must not be accepted through external configuration or request payloads, and resolved secret values must not be emitted.

Non-Goals

Do not move orchestration responsibilities from external callers into Scriptorium.
Do not add adapter-specific business logic in internal/adapter/* packages.
Do not bypass repository/renderer/validator/LLM boundaries by introducing cross-package coupling.

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

3.5 KiB Raw Blame History