# arman0604/finops architecture

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

- Interactive diagram: https://gitdiagram.com/arman0604/finops
- Repository: https://github.com/arman0604/finops

## Overview

1. This repository is a FinOps analytics product split into two major halves: a Python analytics backend that ingests and transforms cloud billing data, and a React + TypeScript frontend that presents command-center style views in the browser.

2. The data domain is centered on cloud cost sources for AWS, Azure, and GCP. The raw inputs live under `data/raw/` as CSVs plus anomaly labels, while cleaned/combined outputs live under `data/processed/`. This separation suggests an offline batch pipeline before anything is visualized.

3. The main Python processing chain is decomposed by responsibility:
   - `data_generator.py` produces synthetic or test billing datasets.
   - `normalizer.py` aligns heterogeneous billing formats into a unified schema.
   - `anomaly_detector.py` and `stream_detector.py` handle batch and near-real-time anomaly detection.
   - `forecasting_engine.py` generates spend predictions.
   - `storage.py` persists results to SQLite.
   These modules are the core analytics engine and likely feed the UI through API endpoints or generated artifacts.

4. Persistence is lightweight and local-first. There is a SQLite database at both `finops.db` and `data/database/finops.db`, which implies the app can operate without external infrastructure. The database is probably used to store normalized spend, anomaly results, and forecast outputs.

5. The application exposes a backend interface via `api.py`, which likely serves processed analytics to the frontend. `chatbot.py` and `dashboard_app.py` suggest additional backend entry points or service wrappers for conversational assistance and dashboard serving, rather than a single monolithic server.

6. The frontend is a Vite-based React app in `src/`. It uses TypeScript, with a clear page-level structure:
   - `CommandCenter` for executive overview
   - `AnomalyWatch` for anomaly monitoring
   - `SpendForecasting` for forecast views
   - `DataUpload` for ingestion workflows
   Shared layout components live under `src/components/Layout/`, and visualization-specific UI lives under `src/components/VisualizationSection/`.

7. Frontend data access is abstracted through `src/data/api.ts`, which likely centralizes calls to the Python backend, while `src/data/mockData.ts` provides local fallback or development data. That implies the UI can run in a partially disconnected mode during development.

8. There is a generated dashboard artifact: `dashboard_generator.py` and `finops_dashboard.html`, plus a copy in `static/finops_dashboard.html`. This indicates a second delivery path besides the React SPA: a prebuilt HTML dashboard that can be served or opened directly, likely containing the same analytics in a static format.

9. The repo also contains an `implementation_plan.md.resolved`, which suggests the project was developed from a planned multi-step architecture with staged implementation. The presence of `test_finops_dataset.csv` reinforces that the project is designed around repeatable local testing with bundled data rather than live cloud integrations.

10. Overall architecture flow: raw cloud billing CSVs enter the Python pipeline, are normalized and stored, then analyzed for anomalies and forecasts. Those results are exposed either through the Python API to the React dashboard or through a generated static HTML dashboard. The browser is the primary interaction layer, while Python owns the data engineering and analytics logic.

Main entry points: [`src/data/api.ts`](https://github.com/arman0604/finops/blob/main/src/data/api.ts) (API client), [`data/processed`](https://github.com/arman0604/finops/tree/main/data/processed) (Processed data), [`api.py`](https://github.com/arman0604/finops/blob/main/api.py) (API), [`src/components/Layout/Layout.tsx`](https://github.com/arman0604/finops/blob/main/src/components/Layout/Layout.tsx) (Layout shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Python analytics"]
  node_data_generator["Generator<br/>dataset synth<br/>[data_generator.py]"]
  node_normalizer["Normalizer<br/>schema alignment<br/>[normalizer.py]"]
  node_batch_detector["Batch detect<br/>anomaly analysis"]
  node_stream_detector["Stream detect<br/>near-real-time<br/>[stream_detector.py]"]
  node_forecasting_engine["Forecasting<br/>spend prediction"]
  node_storage["Storage<br/>db writer<br/>[storage.py]"]
  node_api["API<br/>backend interface<br/>[api.py]"]
  node_chatbot["Chatbot<br/>assistant service<br/>[chatbot.py]"]
  node_dashboard_app["Dashboard app<br/>server wrapper<br/>[dashboard_app.py]"]
  node_dashboard_generator["Dashboard gen<br/>static build"]
end

subgraph group_frontend["React app"]
  node_command_center["Command Center<br/>overview page<br/>[CommandCenter.tsx]"]
  node_anomaly_watch["Anomaly Watch<br/>monitoring page<br/>[AnomalyWatch.tsx]"]
  node_spend_forecasting["Spend Forecasting<br/>forecast page"]
  node_data_upload["Data Upload<br/>ingestion page<br/>[DataUpload.tsx]"]
  node_api_client["API client<br/>data access<br/>[api.ts]"]
  node_mock_data["Mock data<br/>dev fallback<br/>[mockData.ts]"]
  node_layout_shell["Layout shell<br/>shared chrome<br/>[Layout.tsx]"]
  node_viz_section["Viz section<br/>shared visuals"]
end

subgraph group_data["Data assets"]
  node_raw_inputs["Raw billing<br/>cloud CSV inputs"]
  node_processed_data["Processed data<br/>cleaned outputs"]
  node_sqlite_db[("SQLite store<br/>local persistence<br/>[finops.db]")]
  node_static_dashboard["Static dashboard<br/>html artifact"]
end

node_raw_inputs -.->|"seed data"| node_data_generator
node_raw_inputs -->|"ingest"| node_normalizer
node_data_generator -.->|"sample input"| node_normalizer
node_normalizer -->|"write cleaned"| node_processed_data
node_processed_data -->|"analyze"| node_batch_detector
node_processed_data -->|"train/forecast"| node_forecasting_engine
node_processed_data -.->|"incremental feed"| node_stream_detector
node_batch_detector -->|"persist findings"| node_storage
node_stream_detector -->|"persist events"| node_storage
node_forecasting_engine -->|"persist forecasts"| node_storage
node_storage -->|"store"| node_sqlite_db
node_api -->|"read/write"| node_sqlite_db
node_api -.->|"serve data"| node_processed_data
node_chatbot -->|"query"| node_api
node_dashboard_app -->|"serve through"| node_api
node_dashboard_generator -->|"build artifact"| node_static_dashboard
node_api_client -->|"fetch"| node_api
node_api_client -.->|"fallback"| node_mock_data
node_command_center -->|"compose"| node_viz_section
node_anomaly_watch -->|"compose"| node_viz_section
node_spend_forecasting -->|"compose"| node_viz_section
node_data_upload -->|"submit"| node_api_client
node_layout_shell -->|"wraps"| node_command_center
node_layout_shell -->|"wraps"| node_anomaly_watch
node_layout_shell -->|"wraps"| node_spend_forecasting
node_layout_shell -->|"wraps"| node_data_upload
node_api_client -->|"feeds"| node_command_center
node_api_client -->|"feeds"| node_anomaly_watch
node_api_client -->|"feeds"| node_spend_forecasting

click node_raw_inputs "https://github.com/arman0604/finops/tree/main/data/raw"
click node_processed_data "https://github.com/arman0604/finops/tree/main/data/processed"
click node_sqlite_db "https://github.com/arman0604/finops/blob/main/finops.db"
click node_data_generator "https://github.com/arman0604/finops/blob/main/data_generator.py"
click node_normalizer "https://github.com/arman0604/finops/blob/main/normalizer.py"
click node_batch_detector "https://github.com/arman0604/finops/blob/main/anomaly_detector.py"
click node_stream_detector "https://github.com/arman0604/finops/blob/main/stream_detector.py"
click node_forecasting_engine "https://github.com/arman0604/finops/blob/main/forecasting_engine.py"
click node_storage "https://github.com/arman0604/finops/blob/main/storage.py"
click node_api "https://github.com/arman0604/finops/blob/main/api.py"
click node_chatbot "https://github.com/arman0604/finops/blob/main/chatbot.py"
click node_dashboard_app "https://github.com/arman0604/finops/blob/main/dashboard_app.py"
click node_dashboard_generator "https://github.com/arman0604/finops/blob/main/dashboard_generator.py"
click node_static_dashboard "https://github.com/arman0604/finops/blob/main/static/finops_dashboard.html"
click node_command_center "https://github.com/arman0604/finops/blob/main/src/pages/CommandCenter.tsx"
click node_anomaly_watch "https://github.com/arman0604/finops/blob/main/src/pages/AnomalyWatch.tsx"
click node_spend_forecasting "https://github.com/arman0604/finops/blob/main/src/pages/SpendForecasting.tsx"
click node_data_upload "https://github.com/arman0604/finops/blob/main/src/pages/DataUpload.tsx"
click node_api_client "https://github.com/arman0604/finops/blob/main/src/data/api.ts"
click node_mock_data "https://github.com/arman0604/finops/blob/main/src/data/mockData.ts"
click node_layout_shell "https://github.com/arman0604/finops/blob/main/src/components/Layout/Layout.tsx"
click node_viz_section "https://github.com/arman0604/finops/blob/main/src/components/VisualizationSection/VisualizationSection.tsx"

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_data_generator,node_normalizer,node_batch_detector,node_stream_detector,node_forecasting_engine,node_storage,node_api,node_chatbot,node_dashboard_app,node_dashboard_generator toneBlue
class node_command_center,node_anomaly_watch,node_spend_forecasting,node_data_upload,node_api_client,node_mock_data,node_layout_shell,node_viz_section toneAmber
class node_raw_inputs,node_processed_data,node_sqlite_db,node_static_dashboard toneMint
```

## Components

### Python analytics

Batch analytics, API, and dashboard generation

- [Generator](https://github.com/arman0604/finops/blob/main/data_generator.py): dataset synth · Produces synthetic or test billing datasets · `data_generator.py`
- [Normalizer](https://github.com/arman0604/finops/blob/main/normalizer.py): schema alignment · Converts heterogeneous billing formats into a unified schema · `normalizer.py`
- [Batch detect](https://github.com/arman0604/finops/blob/main/anomaly_detector.py): anomaly analysis · Detects anomalies from processed billing data · `anomaly_detector.py`
- [Stream detect](https://github.com/arman0604/finops/blob/main/stream_detector.py): near-real-time · Handles streaming or incremental anomaly detection · `stream_detector.py`
- [Forecasting](https://github.com/arman0604/finops/blob/main/forecasting_engine.py): spend prediction · Generates spend forecasts from historical data · `forecasting_engine.py`
- [Storage](https://github.com/arman0604/finops/blob/main/storage.py): db writer · Persists normalized, anomaly, and forecast outputs · `storage.py`
- [API](https://github.com/arman0604/finops/blob/main/api.py): backend interface · Serves analytics data to the frontend and other clients · `api.py`
- [Chatbot](https://github.com/arman0604/finops/blob/main/chatbot.py): assistant service · Conversational wrapper around FinOps analytics · `chatbot.py`
- [Dashboard app](https://github.com/arman0604/finops/blob/main/dashboard_app.py): server wrapper · Backend entry point for dashboard serving · `dashboard_app.py`
- [Dashboard gen](https://github.com/arman0604/finops/blob/main/dashboard_generator.py): static build · Generates the standalone HTML dashboard artifact · `dashboard_generator.py`

### React app

Browser UI and shared components

- [Command Center](https://github.com/arman0604/finops/blob/main/src/pages/CommandCenter.tsx): overview page · Executive summary and command-center style dashboard · `src/pages/CommandCenter.tsx`
- [Anomaly Watch](https://github.com/arman0604/finops/blob/main/src/pages/AnomalyWatch.tsx): monitoring page · Views anomalies and operational alerts · `src/pages/AnomalyWatch.tsx`
- [Spend Forecasting](https://github.com/arman0604/finops/blob/main/src/pages/SpendForecasting.tsx): forecast page · Displays forecast trends and predictions · `src/pages/SpendForecasting.tsx`
- [Data Upload](https://github.com/arman0604/finops/blob/main/src/pages/DataUpload.tsx): ingestion page · Supports upload-driven ingestion workflows · `src/pages/DataUpload.tsx`
- [API client](https://github.com/arman0604/finops/blob/main/src/data/api.ts): data access · Centralized frontend calls to backend services · `src/data/api.ts`
- [Mock data](https://github.com/arman0604/finops/blob/main/src/data/mockData.ts): dev fallback · Local fallback datasets for development and disconnected use · `src/data/mockData.ts`
- [Layout shell](https://github.com/arman0604/finops/blob/main/src/components/Layout/Layout.tsx): shared chrome · Header, sidebar, and app layout structure · `src/components/Layout/Layout.tsx`
- [Viz section](https://github.com/arman0604/finops/blob/main/src/components/VisualizationSection/VisualizationSection.tsx): shared visuals · Reusable visualization section for page-level charts · `src/components/VisualizationSection/VisualizationSection.tsx`

### Data assets

Raw inputs, processed outputs, and local persistence

- [Raw billing](https://github.com/arman0604/finops/tree/main/data/raw): cloud CSV inputs · AWS, Azure, and GCP billing sources plus anomaly labels · `data/raw`
- [Processed data](https://github.com/arman0604/finops/tree/main/data/processed): cleaned outputs · Unified and derived billing outputs used by analytics and UI · `data/processed`
- [SQLite store](https://github.com/arman0604/finops/blob/main/finops.db): local persistence · Local FinOps database for normalized spend and analysis results · `finops.db`
- [Static dashboard](https://github.com/arman0604/finops/blob/main/static/finops_dashboard.html): html artifact · Prebuilt dashboard for direct serving or offline use · `static/finops_dashboard.html`

## Connections

- Raw billing → Generator: seed data · Synthetic and test data can augment or replace raw inputs
- Raw billing → Normalizer: ingest · Raw cloud billing files are normalized into a unified schema
- Generator → Normalizer: sample input · Generated datasets follow the same normalization path
- Normalizer → Processed data: write cleaned · Unified billing data is materialized as processed outputs
- Processed data → Batch detect: analyze · Batch anomaly detection runs on cleaned billing data
- Processed data → Forecasting: train/forecast · Historical spend drives predictions
- Processed data → Stream detect: incremental feed · Processed data can also support streaming-style checks
- Batch detect → Storage: persist findings · Anomaly results are saved for later retrieval
- Stream detect → Storage: persist events · Streaming detections are stored locally
- Forecasting → Storage: persist forecasts · Forecast outputs are written to the local store
- Storage → SQLite store: store · Results are persisted in SQLite
- API → SQLite store: read/write · Backend interface serves and updates analytics data
- API → Processed data: serve data · API may also expose processed artifacts directly
- Chatbot → API: query · Conversational layer consumes backend analytics endpoints
- Dashboard app → API: serve through · Dashboard server wrapper exposes backend data
- Dashboard gen → Static dashboard: build artifact · Generates the standalone HTML dashboard
- API client → API: fetch · Frontend data access layer calls the Python API
- API client → Mock data: fallback · Local mock data supports development and offline mode
- Command Center → Viz section: compose · Primary overview page uses shared visualization UI
- Anomaly Watch → Viz section: compose · Monitoring page reuses shared charting sections
- Spend Forecasting → Viz section: compose · Forecast page reuses visualization components
- Data Upload → API client: submit · Upload workflows send data through the frontend data layer
- Layout shell → Command Center: wraps · Shared layout hosts the main pages
- Layout shell → Anomaly Watch: wraps · Shared layout hosts the main pages
- Layout shell → Spend Forecasting: wraps · Shared layout hosts the main pages
- Layout shell → Data Upload: wraps · Shared layout hosts the main pages
- API client → Command Center: feeds · Command Center is data-driven from the backend client
- API client → Anomaly Watch: feeds · Anomaly views consume backend data
- API client → Spend Forecasting: feeds · Forecast views consume backend data