Architecture

This page describes the public repository as it existed at v0.6.0. It does not document unreleased work on main.

Principles

From AGENTS.md at that tag:

• The core must remain provider-independent.
• Provider-specific behavior belongs under provider packages.
• Prefer provider-native resource models over premature lowest-common-denominator abstractions.
• The plan engine must never perform mutations.
• Do not introduce destructive reconciliation unless explicitly required.
• v0.1 introduced local identity state in agoraform.state.json. Remote backends, workspaces, locking, encryption, and Terraform-compatible state are out of scope unless a later issue requires them.

v0.6.0 implements agoraform destroy as an explicit command. Removing a resource from the manifest still does not prune it. plan and apply remain non-destructive.

The CLI is a thin adapter around core packages so resource mutations and provider finalizations follow the same ordering for every canonical entry point.

Layout at v0.6.0

cmd/agoraform/          CLI entrypoint
internal/
  apply/                Apply execution
  cli/                  Cobra commands: validate, plan, apply, import, destroy
  config/               Local .agoraform.env loading
  graph/                Resource dependency graph
  importer/             Import YAML emission and identity persistence
  manifest/             YAML load and validation
  plan/                 Non-mutating plan engine
  provider/             Provider registry and interfaces
  resource/             Logical addresses
  state/                Local agoraform.state.json
providers/
  matomo/               Matomo client and resources
  googleads/            Google Ads REST client and resources
  meta/                 Meta Graph/Marketing API client and resources
examples/               Secret-free sample manifests
docs/                   CLI-repo documentation

cmd/agoraform/main.go calls internal/cli.Execute(). Root flags include Cobra --version, which prints the injected SemVer string (0.6.0 for this release).

Providers register with the core. Matomo, Google Ads, and Meta HTTP clients live under their provider packages. Tests use local httptest servers; they must not call production services.

Workflow ownership

manifest + local state
        │
        ▼
validate / configure providers
        │
        ▼
build resource + provider-action plan
        │
        ▼
apply mutations in dependency order
        │
        ▼
provider finalization (for example Matomo publication)

See the tagged repository for package-level details and tests.