# mizcausevic-dev/ai-finops-radar architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/ai-finops-radar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/ai-finops-radar
- Repository: https://github.com/mizcausevic-dev/ai-finops-radar

## Overview

AI FinOps Radar is a Node.js/TypeScript API for attributing and governing AI-model spend: it calculates token costs, evaluates budgets, detects spend anomalies, forecasts month-end totals, and rolls usage up for department chargeback. The principal workflow begins when an external HTTP API consumer requests the dashboard summary; the service combines its deterministic demo usage and budgets with governance calculations and returns a consolidated response. The same API also exposes the calculations individually.

##### HTTP service
- **HTTP API consumer** — **path: null**. An external caller initiates the workflow with an HTTP request; no caller implementation is included in this repository.
- **Express application** — `src/index.ts`. Starts the Express app, installs middleware, serves health status, and mounts the cost, budget, insights, and dashboard routers under `/api`.
- **API routes and dashboard composition** — `src/routes/index.ts`. Validates endpoint inputs, dispatches individual requests to governance functions, and assembles the dashboard summary from usage and budget data.

##### Usage and budget inputs
- **Demo usage ledger** — `src/data/usage.ts`. Defines seeded usage events, computes their costs through the pricing calculator, and aggregates events into a daily cost series; the excerpt is partial.
- **Demo budgets** — `src/data/budgets.ts`. Supplies organization- and department-level monthly budget records used by the API and dashboard.

##### Governance calculations
- **Pricing and cost attribution** — `src/governance/cost-calculator.ts`. Holds the model pricing catalog and computes token costs, cached-input costs, and ranked provider comparisons.
- **Budget evaluation** — `src/governance/budget-tracker.ts`. Calculates utilization, burn rate, projected spend and overrun, and a tiered status with a recommended action.
- **Anomaly detection** — `src/governance/anomaly-detector.ts`. Flags daily-cost outliers using rolling-window statistics, configurable thresholds, and severity explanations.
- **Month-end forecasting** — `src/governance/forecaster.ts`. Projects month-end spend using linear regression when enough observations are available and otherwise falls back to a mean-based estimate; returns a confidence interval.
- **Department chargeback** — `src/governance/chargeback.ts`. Groups usage events by department and reports spend, token counts, top providers/models/projects, and each department’s share of organization spend.

##### Request contracts
- **Input validation schemas** — `src/schemas/validation-schemas.ts`. Defines Zod payload schemas for cost, budget, anomaly, forecast, and chargeback routes.

##### Relationships
- **HTTP API consumer -> Express application**: sends HTTP requests; the README documents health and `/api` endpoints, and the app installs the routers.
- **Express application -> API routes and dashboard composition**: mounts the routers at the documented API prefixes.
- **API routes and dashboard composition -> Input validation schemas**: calls `safeParse` on request bodies before dispatching calculations.
- **API routes and dashboard composition -> Pricing and cost attribution**: invokes cost computation, provider comparison, and catalog lookup for cost endpoints.
- **API routes and dashboard composition -> Budget evaluation**: evaluates submitted budgets and dashboard organization/department budgets.
- **API routes and dashboard composition -> Anomaly detection**: invokes detection for submitted series and for the dashboard series.
- **API routes and dashboard composition -> Month-end forecasting**: invokes forecasting for submitted data and for the dashboard series.
- **API routes and dashboard composition -> Department chargeback**: invokes rollup for submitted events and for dashboard usage.
- **API routes and dashboard composition -> Demo usage ledger**: reads seeded events and obtains the daily series for the dashboard response.
- **API routes and dashboard composition -> Demo budgets**: reads the budget list for listing and dashboard evaluation.
- **Demo usage ledger -> Pricing and cost attribution**: computes each seeded event’s cost and provider when constructing usage events.
- **Demo usage ledger -> API routes and dashboard composition**: exposes usage events and a daily cost-series aggregation used in dashboard composition.

##### Coverage limits
The source sample omits portions of the usage ledger and does not include every repository file’s contents. The README documents additional behavior, but the sampled code does not establish a live invoice source, persistent storage, alert delivery, authentication, or an implemented dashboard UI; these are not represented as runtime components.

Main entry points: [`src/routes/index.ts`](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/routes/index.ts) (API Routes & Dashboard), [`src/data/usage.ts`](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/data/usage.ts) (Demo Usage Ledger), [`src/index.ts`](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/index.ts) (Express Application), [`src/governance/cost-calculator.ts`](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/governance/cost-calculator.ts) (Pricing & Cost Attribution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP Service"]
  node_express["Express Application<br/>API"]
  node_routes["API Routes &amp; Dashboard<br/>[index.ts]"]
  node_schemas["Input Validation Schemas"]
end

subgraph group_inputs["Demo Inputs"]
  node_usage["Demo Usage Ledger<br/>data source"]
  node_budgets["Demo Budgets<br/>data source"]
end

subgraph group_governance["Governance Calculations"]
  node_pricing["Pricing &amp; Cost Attribution<br/>calculation"]
  node_budget["Budget Evaluation<br/>calculation"]
  node_anomaly["Anomaly Detection<br/>calculation"]
  node_forecast["Month-End Forecasting<br/>calculation"]
  node_chargeback["Department Chargeback<br/>calculation"]
end

node_consumer(("HTTP API Consumer<br/>external"))

node_consumer -->|"sends requests"| node_express
node_express -->|"mounts routers"| node_routes
node_routes -->|"validates inputs"| node_schemas
node_routes -->|"computes costs"| node_pricing
node_routes -->|"evaluates budgets"| node_budget
node_routes -->|"detects anomalies"| node_anomaly
node_routes -->|"forecasts spend"| node_forecast
node_routes -->|"rolls up usage"| node_chargeback
node_routes -->|"reads usage"| node_usage
node_routes -->|"reads budgets"| node_budgets
node_usage -->|"computes event costs"| node_pricing
node_usage -->|"provides usage data"| node_routes

click node_express "https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/index.ts"
click node_routes "https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/routes/index.ts"
click node_schemas "https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/schemas/validation-schemas.ts"
click node_usage "https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/data/usage.ts"
click node_budgets "https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/data/budgets.ts"
click node_pricing "https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/governance/cost-calculator.ts"
click node_budget "https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/governance/budget-tracker.ts"
click node_anomaly "https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/governance/anomaly-detector.ts"
click node_forecast "https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/governance/forecaster.ts"
click node_chargeback "https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/governance/chargeback.ts"

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_express,node_routes,node_schemas toneBlue
class node_usage,node_budgets toneAmber
class node_pricing,node_budget,node_anomaly,node_forecast,node_chargeback,node_consumer toneMint
```

## Components

### HTTP Service

- [Express Application](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/index.ts): API · `src/index.ts`
- [API Routes & Dashboard](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/routes/index.ts): API · `src/routes/index.ts`
- [Input Validation Schemas](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/schemas/validation-schemas.ts): validation · `src/schemas/validation-schemas.ts`

### Demo Inputs

- [Demo Usage Ledger](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/data/usage.ts): data source · `src/data/usage.ts`
- [Demo Budgets](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/data/budgets.ts): data source · `src/data/budgets.ts`

### Governance Calculations

- [Pricing & Cost Attribution](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/governance/cost-calculator.ts): calculation · `src/governance/cost-calculator.ts`
- [Budget Evaluation](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/governance/budget-tracker.ts): calculation · `src/governance/budget-tracker.ts`
- [Anomaly Detection](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/governance/anomaly-detector.ts): calculation · `src/governance/anomaly-detector.ts`
- [Month-End Forecasting](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/governance/forecaster.ts): calculation · `src/governance/forecaster.ts`
- [Department Chargeback](https://github.com/mizcausevic-dev/ai-finops-radar/blob/main/src/governance/chargeback.ts): calculation · `src/governance/chargeback.ts`

### Other components

- **HTTP API Consumer**: external

## Connections

- HTTP API Consumer → Express Application: sends requests
- Express Application → API Routes & Dashboard: mounts routers
- API Routes & Dashboard → Input Validation Schemas: validates inputs
- API Routes & Dashboard → Pricing & Cost Attribution: computes costs
- API Routes & Dashboard → Budget Evaluation: evaluates budgets
- API Routes & Dashboard → Anomaly Detection: detects anomalies
- API Routes & Dashboard → Month-End Forecasting: forecasts spend
- API Routes & Dashboard → Department Chargeback: rolls up usage
- API Routes & Dashboard → Demo Usage Ledger: reads usage
- API Routes & Dashboard → Demo Budgets: reads budgets
- Demo Usage Ledger → Pricing & Cost Attribution: computes event costs
- Demo Usage Ledger → API Routes & Dashboard: provides usage data