# joselinepraveena/finops-cost-estimator-agent architecture

> Architecture diagram of the GitHub repository joselinepraveena/finops-cost-estimator-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joselinepraveena/finops-cost-estimator-agent
- Repository: https://github.com/joselinepraveena/finops-cost-estimator-agent

## Overview

#### Purpose and entry points

FinOps Cost Estimator is an Azure-first cost forecasting MVP. It accepts natural-language workloads or structured JSON, deterministically calculates monthly cost scenarios, and produces web, CLI, Markdown, CSV, and Excel outputs.

Primary launch paths:
- Module dispatcher: `finops_estimator/__main__.py`
- CLI commands (`ask`, `estimate`, `serve`): `finops_estimator/cli.py`
- HTTP/web application: `finops_estimator/api.py`
- Browser client: `finops_estimator/web/static/index.html`

#### Input interpretation boundary

Natural-language requests are converted into a structured workload specification before pricing. Parsing can use optional Azure OpenAI credentials, but has local parsing behavior so offline execution remains possible.

- Workload parsing and normalization: `finops_estimator/parser.py`
- Optional Azure OpenAI integration: `finops_estimator/openai_client.py`
- Domain workload, pricing, and result models: `finops_estimator/models.py`

The central architectural rule is enforced here and downstream: AI interprets workload intent; code, not the model, computes price arithmetic.

#### Deterministic estimation engine

The core calculation pipeline consumes the normalized workload model and constructs priced line items, scenario comparisons, assumptions, ranges, sensitivities, and what-if results. It covers Azure VM/AKS, Azure SQL, storage, load balancing, egress, backup, and logs.

- Primary orchestration and calculations: `finops_estimator/engine.py`
- Cost/result schemas shared across stages: `finops_estimator/models.py`
- Static fallback price data: `finops_estimator/fallback_prices.py`

This is the main trust boundary: all totals originate from engine logic and price records, rather than narrative generation.

#### Price acquisition and resilience

Live pricing is obtained from the external Azure Retail Prices API. The estimator can instead use its embedded dated catalog, explicitly via `--offline` or when the retail service is unavailable. `FINOPS_LIVE_PRICES=0` supports deterministic non-live runs.

- Retail API client and lookup logic: `finops_estimator/retail.py`
- Offline catalog: `finops_estimator/fallback_prices.py`
- Engine integration point: `finops_estimator/engine.py`

Price lookup is therefore isolated from workload interpretation and scenario arithmetic.

#### Scenario and recommendation flow

The engine evaluates on-demand, one-year and three-year Reserved Instance, Savings Plan, and optimized options. It also supports region comparisons, SKU rightsizing, storage-tier changes, and DR-footprint changes. The resulting structured estimate feeds a narrative layer that creates an executive-facing explanation and chargeback-tag guidance.

- Scenario calculation: `finops_estimator/engine.py`
- Narrative generation: `finops_estimator/narrative.py`
- Optional model-backed explanation: `finops_estimator/openai_client.py`

Narrative output is downstream of calculated results and should not mutate estimates.

#### Delivery surfaces and exports

The CLI is the primary automation interface; `serve` exposes an HTTP API that backs the lightweight static conversational UI. Structured estimation output can be rendered for download or sharing.

- CLI interface: `finops_estimator/cli.py`
- API/server surface: `finops_estimator/api.py`
- Static web UI: `finops_estimator/web/static/app.js`
- Markdown/CSV/Excel export: `finops_estimator/export.py`

Runtime is Python, with optional Azure OpenAI and live Azure Retail Prices API dependencies. No later-phase integrations such as Cost Management exports, AI Search, Teams, Power BI, or RBAC/audit are present.

Main entry points: [`finops_estimator/engine.py`](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/engine.py) (Cost Engine), [`finops_estimator/cli.py`](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/cli.py) (CLI: ask, estimate, serve), [`finops_estimator/api.py`](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/api.py) (HTTP Application), [`finops_estimator/narrative.py`](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/narrative.py) (Executive Narrative)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry Surfaces"]
  node_dispatcher["Module Dispatcher<br/>Python entry point<br/>[__main__.py]"]
  node_cli["CLI: ask, estimate, serve<br/>Python CLI<br/>[cli.py]"]
  node_api["HTTP Application<br/>Python API<br/>[api.py]"]
  node_web_ui["Browser UI<br/>static web client<br/>[index.html]"]
  node_web_app["Web Client Logic<br/>JavaScript<br/>[app.js]"]
end

subgraph group_interpret["Interpretation"]
  node_parser["Workload Parser<br/>normalization<br/>[parser.py]"]
  node_openai{{"Azure OpenAI<br/>optional AI service<br/>[openai_client.py]"}}
  node_models["Domain Models<br/>shared schemas<br/>[models.py]"]
end

subgraph group_estimate["Deterministic Estimation"]
  node_engine["Cost Engine<br/>calculation orchestrator<br/>[engine.py]"]
  node_retail["Retail Price Lookup<br/>pricing client<br/>[retail.py]"]
  node_fallback[("Embedded Price Catalog<br/>offline price data<br/>[fallback_prices.py]")]
end

subgraph group_delivery["Narrative &amp; Delivery"]
  node_narrative["Executive Narrative<br/>result explanation<br/>[narrative.py]"]
  node_export["Markdown, CSV &amp; Excel Export<br/>renderers<br/>[export.py]"]
end

node_azure_retail{{"Azure Retail Prices API<br/>external API"}}

node_dispatcher -->|"dispatches commands"| node_cli
node_cli -->|"natural-language input"| node_parser
node_cli -->|"structured estimate"| node_engine
node_cli -->|"serve"| node_api
node_api -->|"requests"| node_parser
node_api -->|"estimation requests"| node_engine
node_web_ui -->|"loads"| node_web_app
node_web_app -->|"HTTP requests"| node_api
node_parser -.->|"optional intent interpretation"| node_openai
node_parser -->|"normalized workload"| node_models
node_models -->|"workload and result schemas"| node_engine
node_engine -->|"live price lookup"| node_retail
node_retail -->|"queries"| node_azure_retail
node_engine -.->|"offline/unavailable fallback"| node_fallback
node_engine -->|"calculated estimate"| node_narrative
node_narrative -.->|"optional explanation generation"| node_openai
node_engine -->|"structured results"| node_export
node_narrative -->|"explanation output"| node_cli
node_export -->|"download/share formats"| node_cli
node_narrative -->|"response narrative"| node_api
node_export -->|"export responses"| node_api

click node_dispatcher "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/__main__.py"
click node_cli "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/cli.py"
click node_api "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/api.py"
click node_web_ui "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/web/static/index.html"
click node_web_app "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/web/static/app.js"
click node_parser "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/parser.py"
click node_openai "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/openai_client.py"
click node_models "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/models.py"
click node_engine "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/engine.py"
click node_retail "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/retail.py"
click node_fallback "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/fallback_prices.py"
click node_narrative "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/narrative.py"
click node_export "https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/export.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dispatcher,node_cli,node_api,node_web_ui,node_web_app toneBlue
class node_parser,node_openai,node_models toneAmber
class node_engine,node_retail,node_fallback toneMint
class node_narrative,node_export toneRose
class node_azure_retail toneNeutral
```

## Components

### Entry Surfaces

- [Module Dispatcher](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/__main__.py): Python entry point · `finops_estimator/__main__.py`
- [CLI: ask, estimate, serve](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/cli.py): Python CLI · Primary automation interface. · `finops_estimator/cli.py`
- [HTTP Application](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/api.py): Python API · Serves estimation endpoints and web client. · `finops_estimator/api.py`
- [Browser UI](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/web/static/index.html): static web client · `finops_estimator/web/static/index.html`
- [Web Client Logic](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/web/static/app.js): JavaScript · `finops_estimator/web/static/app.js`

### Interpretation

- [Workload Parser](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/parser.py): normalization · Converts natural language into a workload specification, including offline parsing. · `finops_estimator/parser.py`
- [Azure OpenAI](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/openai_client.py): optional AI service · Interprets workload intent and can generate explanations. · `finops_estimator/openai_client.py`
- [Domain Models](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/models.py): shared schemas · Workload, price, and result models shared across stages. · `finops_estimator/models.py`

### Deterministic Estimation

- [Cost Engine](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/engine.py): calculation orchestrator · Deterministically builds line items, scenarios, ranges, sensitivities, and what-if results. · `finops_estimator/engine.py`
- [Retail Price Lookup](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/retail.py): pricing client · Queries live Azure Retail Prices and isolates lookup from calculation. · `finops_estimator/retail.py`
- [Embedded Price Catalog](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/fallback_prices.py): offline price data · Dated fallback catalog for offline or unavailable live pricing. · `finops_estimator/fallback_prices.py`

### Narrative & Delivery

- [Executive Narrative](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/narrative.py): result explanation · Creates recommendations and chargeback-tag guidance from calculated estimates. · `finops_estimator/narrative.py`
- [Markdown, CSV & Excel Export](https://github.com/joselinepraveena/finops-cost-estimator-agent/blob/main/finops_estimator/export.py): renderers · `finops_estimator/export.py`

### Other components

- **Azure Retail Prices API**: external API

## Connections

- Module Dispatcher → CLI: ask, estimate, serve: dispatches commands
- CLI: ask, estimate, serve → Workload Parser: natural-language input
- CLI: ask, estimate, serve → Cost Engine: structured estimate
- CLI: ask, estimate, serve → HTTP Application: serve
- HTTP Application → Workload Parser: requests
- HTTP Application → Cost Engine: estimation requests
- Browser UI → Web Client Logic: loads
- Web Client Logic → HTTP Application: HTTP requests
- Workload Parser → Azure OpenAI: optional intent interpretation
- Workload Parser → Domain Models: normalized workload
- Domain Models → Cost Engine: workload and result schemas
- Cost Engine → Retail Price Lookup: live price lookup
- Retail Price Lookup → Azure Retail Prices API: queries
- Cost Engine → Embedded Price Catalog: offline/unavailable fallback
- Cost Engine → Executive Narrative: calculated estimate · Narrative cannot alter price arithmetic.
- Executive Narrative → Azure OpenAI: optional explanation generation
- Cost Engine → Markdown, CSV & Excel Export: structured results
- Executive Narrative → CLI: ask, estimate, serve: explanation output
- Markdown, CSV & Excel Export → CLI: ask, estimate, serve: download/share formats
- Executive Narrative → HTTP Application: response narrative
- Markdown, CSV & Excel Export → HTTP Application: export responses