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
  application/
    api/                  # Runtime, collect, analyze, report
    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
  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

Each stage persists structured output so you can rerun report without hitting cloud APIs again.

Step sequence: Roadmap.