84 lines
3.5 KiB
Markdown
84 lines
3.5 KiB
Markdown
# 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](../internal/overview.md).
|
|
|
|
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](../cli.md), [configuration](../config.md), [HTTP API](../api.md),
|
|
[public Go package](../consumers/pkg-scriptorium.md), and
|
|
[integration](../integrations/) 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](testing.md). Documentation ownership and maintenance rules are
|
|
defined by the [documentation policy](documentation.md).
|
|
|
|
## 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/`.
|