policy/docs/policy/architecture.md

Architecture Policy

Base Policy Version: 1.3

Last Updated: 2026-09-27

Base Policy Template

When adopting this policy:

1. Replace the application-specific guidance below with the repository's purpose, adopted architectural constraints, and relevant non-goals;
2. Distinguish rules governing development from descriptions of implemented structure. Keep proposed changes and implementation status in their canonical documents under the documentation policy;
3. Reference supporting documents when they contain useful information;
4. Update the Last Updated field to the current date; and
5. Remove this heading (Base Policy Template) and the associated text.

This template requires substantial customization. Select topics relevant to the application from the examples below.

Purpose And Ownership

The adopted policy defines the application's purpose and the architectural constraints contributors must follow. It owns system boundaries, responsibility and dependency rules, established invariants, and explicit non-goals.

Describe the concrete package inventory and implementation mechanics in internal documentation. Link to canonical public contracts for their exact behavior and to ADRs for decision rationale.

Architectural Approach

Hexagonal architecture is strongly recommended, including encapsulating external integrations and APIs within internal adapters. Keep domain and application logic independent of external integration details, and make dependency direction clear in the adopted policy.

Implement that separation with proportionate, idiomatic code. Choose interfaces and package layout to serve the application's actual boundaries. Use adapters for collaborators with external integration responsibilities.

Adopted Constraints And Implemented Structure

Architectural constraints govern current and future development. Record implemented structure accurately, proposals and implementation status in the roadmap, and significant decisions and rationale in ADRs. Describe a target structure as implemented when its changes land.

Constraints must reflect deliberately selected requirements and decisions. Do not promote incidental implementation choices into architectural invariants.

Application-Specific Topics

Replace this guidance with the relevant decisions for the application, such as:

• its purpose, overall system shape, and responsibility boundaries;
• dependency direction and the treatment of external integrations;
• whether a library provides a flexible API for varied consumers or an opinionated API that enforces deliberately selected conventions;
• whether orchestration supports a full DAG or an ordered sequence of stages;
• any deliberately selected libraries that form an architectural dependency;
• established invariants that future changes must preserve; and
• explicit architectural non-goals.

Trust Boundaries And Threat Scope

Where useful, state the trust boundaries and threat scenarios relevant to the application's adopted requirements, along with scenarios it explicitly excludes. For example, distinguish handling untrusted application input from defending against a privileged actor concurrently modifying the host filesystem.

Threat exclusions define the scope of the adopted requirements. Base defenses and guarantees on those requirements and raise unsettled scope for a deliberate decision under the agent policy.

Keep this discussion proportionate to the application. A separate threat assessment or security document is optional when adopting this template. Configuration, operations, and internal documents retain ownership of credential supply, runtime handling, and implementation mechanisms under the documentation policy.