policy/docs/policy/architecture.md

Architecture Policy

Base Policy Version: 1.1

Last Updated: 2026-09-25

Base Policy Template

This document is the base template for the canonical architecture policy. Repositories that implement this policy should:

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 only when they contain useful information. Do not create TODO documents solely to populate an architectural outline;
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 that matter to the application; the examples below are not a checklist of required subsystems, interfaces, or supporting documents.

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 rather than repeating those definitions here.

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. The preference does not by itself require an interface for every type, a fixed directory tree, or adapters for collaborators that have no external integration responsibility.

Adopted Constraints And Implemented Structure

An adopted architectural constraint governs development. It is not evidence that every component or capability to which it could apply already exists. For example, a rule that external integrations belong behind adapters can apply to future integrations without implying that those integrations are implemented or planned.

Describe implemented structure accurately. Keep proposals and implementation status in the roadmap, and significant decisions and their rationale in ADRs. When an accepted decision requires changing existing structure, identify that transition through those documents; do not describe the target structure as already implemented or treat acceptance as proof of compliance.

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.

These statements should explain the scope of the adopted architectural constraints. Excluding a scenario is not a claim that it cannot occur. Do not infer additional defenses or guarantees merely because a hypothetical threat can be described. Unsettled scope decisions should be raised for a deliberate decision under the agent policy.

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