Architecture

This page describes the public repository as it existed at v0.3.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.

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.3.0

cmd/agoraform/          CLI entrypoint
internal/
  apply/                Apply execution
  cli/                  Cobra commands: validate, plan, apply, import
  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
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.3.0 for this release).

Providers register with the core. Matomo and Google Ads 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 resource creates/updates
(prerequisites first)
        │
        ▼
persist identities
        │
        ▼
provider finalization actions

Plan uses read-only provider contracts. Optional provider finalization planning is also required to be non-mutating. Apply executes finalization only after successful resource convergence.

See contributing for the build and pull-request workflow.