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/andinternal/. context.Contexton I/O;zerologfor 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.