Architecture

Hexagonal layout, product principles, and engineering constraints.

Hexagonal layout: cloud SDKs, SQLite, and HTTP sit in adapters. Domain logic and rules stay free of that infrastructure.

Package layout

cmd/
  main.go                 # Entry point
internal/
  adapters/               # CLI, config, logging, cloud collectors, SQLite, terraform-input
  application/
    api/                  # Runtime, collect, analyze, report, terraform, workspace
    ports/                # Adapter interfaces
    rules/                # Rule engine
    billing/              # Cost attribution
    metrics/              # Utilization signals
    pricing/              # Catalog lookups
    savings/              # Savings math, overlap dedup
    report/               # Report DTOs and rendering
    terraform/            # IaC correlation, plan analysis, remediation hints
    collect/              # Resumable snapshot lifecycle
    security/             # Path validation, encryption, collection budgets
    audit/                # Append-only workspace audit log
  domain/               # Entities and value objects
testdata/fixtures/        # Offline YAML

Product rules

  • Calculations are deterministic. Optional AI layers interpret output; they do not fabricate measurements.
  • Findings carry evidence, observation time, source, assumptions, confidence, and remediation text.
  • Collectors are read-only against cloud APIs.
  • Credentials and metadata stay local unless the user opts into an external AI provider.
  • Provider SDK types do not enter internal/application/domain.
  • Missing signals surface as capability gaps. Adapters do not infer values.

Engineering constraints

  • Standard Go layout under cmd/ and internal/.
  • context.Context on I/O; zerolog for logs.
  • SQLite behind a repository port; embedded forward-only migrations.
  • Explicit timestamps, currencies, units, billing periods.
  • Fixtures for offline work on every provider adapter.

Data flow

collect → SQLite snapshot → analyze → AnalysisRun → report → HTML/JSON
                              ↓
                    terraform correlate ← state/plan JSON (optional)

Each stage writes to SQLite so you can rerun report or terraform correlate without calling cloud APIs. Terraform correlation reads exported JSON only.

Workspace commands touch the SQLite file and report files under retention and permission settings in config.

Step sequence: Roadmap.