Architecture

Simple parts.
Clear boundaries.

spendlens is a Python CLI that turns AWS APIs into SQL with Steampipe, runs company-specific controls with Powerpipe, and keeps every result in a local history that reports, notifications and the AI assistant read.

System context

Who uses spendlens, and what it talks to.

PersonFinOps / platform engineerterminal, assumed AWS rolePersonEngineering managerreads reports, asks questionsSystemCI schedulerGitLab CI / GitHub ActionsSoftware systemspendlensFinOps CLI · read-onlyExternal systemAWS account(s)resource APIs · CloudWatchExternal systemAWS billing APIsCost Explorer · Budgets · Opt. HubExternal systemLLM providerBedrock · Anthropic · OpenAI · AzureExternal systemSlack / Teamsincoming webhooksruns commandsasks · opens reportspendlens reportreads inventory + metricsreads cost, budgets, recsquestion + tool resultsposts summary
C4 level 1 (context). spendlens sits between the people and pipelines that ask cost questions and the systems it reads. Every arrow into AWS is a read; nothing in AWS is ever changed.

Containers

What runs inside spendlens, and how data moves between the parts.

spendlens (one Python package on the machine or CI runner)CallerYou / CIspendlens <command>ContainerCLI + feature pluginsTyper · config layersContainerPowerpipe + bundled mod415 controls (tags, rightsize, waste)ContainerEnginescost · anomaly · forecast · savingsContainerSteampipe (Postgres)aws plugin · read-only sessionContainerHistory storeSQLite: runs · findings · costContainerAI agent + SQL guardtool loop · 3 read-only layersContainerRendererstable · CSV · JSON · HTMLExternalAWS APIsrole from terminal / OIDCExternalLLM providerofficial SDKsExternalSlack / Teamswebhook (env var)invokesruns benchmarkcontrol SQLcost questionsbounded SQLAPI readssave runhistory_query--live onlymessagesnotify (summary)
C4 level 2 (containers). Controls run through Powerpipe; cost questions go straight to Steampipe as bounded SQL; every run lands in the SQLite history, which the dashboard, notify and the AI assistant read without touching AWS again.

Controls via Powerpipe

Tag, rightsizing and waste rules are SQL controls in a bundled mod. Thresholds come from finops.yaml and are passed as mod variables, so one file holds your company standards.

Cost via direct SQL

Cost diff, trend, showback, anomalies and forecast query Steampipe's Cost Explorer tables directly. Each period is one bounded API call, because exactly one period_start/period_end pair is sent.

History as the hub

Every run is saved to SQLite: findings, cost rows, the parameters used and CI metadata. The dashboard, notify, history diff and ask read it offline.

Plugins everywhere

Built-in features use the same registry as third-party plugins: commands, Powerpipe mods, savings estimators, AI tools and dashboard tabs.

A scheduled report run

What happens when the pipeline fires.

CI schedulerAWS STS + APIsspendlensPowerpipeSteampipeHistory DBSlack / TeamsOIDC token → AssumeRoleWithWebIdentityshort-lived read-only credentialsrestore history.db (S3 / cache)spendlens report --out reportseach step = its own process; a failure never stops the restbenchmark run tags / rightsize / wastecontrol SQL (read-only session)Describe* / List* / GetMetricStatisticsresults JSON → findings + $ estimatescost diff · anomalies · forecast: bounded SQLGetCostAndUsage / GetCostForecastsave each run (findings, cost rows, params)dashboard + savings summary from historynotify: summary + new alarms since last runsave history.db · keep reports/ artifact
A scheduled run. The pipeline holds no AWS keys: it trades an OIDC token for a read-only role. spendlens writes every result to the history DB, so the dashboard, notifications and next week's 'what changed' all come from data already collected.

Asking the AI assistant

How a question becomes an answer, and why it can't change anything.

Youspendlens askLLM providerSQL guardHistory DBSteampipe“Why did EC2 go up last month?”system prompt + question + tool schemastool_use: history_overviewlatest run per feature (read-only)tool_resulttool_use: history_query(SELECT …)1 · parse: single read-only SELECT?2 · mode=ro + query_only + authorizerrows (capped, truncated)with --live only: 3 · read-only Steampipe session + timeout + row captool_result (data, never instructions)answer citing runs and numbersanswer + audit trail (--show-tools)
One question. The model never touches a database: it asks for a query, spendlens checks it with a SQL parser, then runs it on a connection that cannot write. Live AWS is only reachable with --live.

Credentials

Steampipe's AWS plugin uses the standard credential chain: the role assumed in your terminal, AWS_PROFILE, SSO, or OIDC web identity in CI. spendlens stores no AWS keys.

Three read-only layers

1: a sqlglot parser allows one SELECT. 2: the history DB opens read-only with a SQLite authorizer. 3: Steampipe sessions run with default_transaction_read_only, a timeout and a row cap.

Any LLM, native SDKs

Claude goes through the official Anthropic SDK (Anthropic API or Bedrock with your AWS role). OpenAI, Azure OpenAI and OpenAI-compatible servers go through the official OpenAI SDK.

Tested at three layers

Unit tests; integration tests driving real SDKs and Powerpipe; and system tests that run the CLI end to end through Steampipe against an AWS emulator (Moto). An offline checker validates every control's SQL against the plugin schema.