Architecture

These views explain how Octoform 0.5 turns reviewed YAML into observable, planned, and explicitly confirmed GitHub operations. They describe the released system, which governs an account as well as its repositories, and exclude the Actions, environments and secret-management features planned for later lines.

Every diagram is rendered locally from versioned PlantUML source. The public site serves static SVG files and sends neither documentation content nor source code to an external diagram service.

Requirements views

Artefact	Purpose
Requirements overview	Explain how the requirements artefacts are recorded and why they are required to agree with each other.
Actors and use cases	Define each human, automation, application, and external-system role and the individual goals they pursue.
Operator context	Place every use case on one state model: what the operator holds, and which use case moves them.
Use-case specifications	Specify each use case as a conversation, with preconditions and the states it can end on.
System context	Show how those actors enter through the CLI or ESM API and how Octoform reaches GitHub.

Software structure

Artefact	Purpose
Container view	Locate the Node.js process, local inputs, credential boundary, transport, output, and GitHub state.
Runtime components	Explain responsibilities and dependencies inside the process.
Domain model	Define declared, observed, capability, planned, and applied concepts.

Behavior and state

Artefact	Purpose
Configuration loading	Trace recursive imports, relative paths, composition, and validation.
Policy resolution	Resolve defaults, type policy, named overrides, null, and management boundaries.
Repository selection	Explain owner-aware discovery, exclusions, filters, archive handling, and observation scope.
Plan and apply	Sequence reads, planning, confirmation, grouped mutation, and results.
Owner reconciliation	Reconcile the account itself, and derive apply order from a dependency graph rather than from written order.
State models	Follow configuration and individual changes through their complete lifecycles.

Trust and delivery

Artefact	Purpose
Trust and data flow	Identify credential, configuration, network, GitHub, and logging boundaries.
Automation patterns	Separate pull-request planning, scheduled auditing, and protected apply.
Release pipelines	Relate application patches, documentation lines, editorial publication tags, and deployment.

Cross-cutting safety properties

1. Omission means unmanaged, not disabled or deleted.
2. Unreadable state remains distinguishable from an absent value, whichever transport failed to read it.
3. Capability comes from GitHub evidence, not hard-coded plan names.
4. apply uses the executable changes displayed in that invocation.
5. Blocked changes remain reportable and never reach the applier.
6. Endpoint groups can fail independently; successful groups are not rolled back automatically.
7. Undeclared rulesets, environments, branches, files, teams, property definitions, labels and milestones are not deleted. Removal is stated.
8. A change whose prerequisite failed is blocked, not attempted.
9. Nothing removes the last person able to undo the change: not the only organization owner, and not the account the run is authenticated as.

The audited behavior baseline records the published package and API evidence behind these properties.