# rahulsayz/gcp-cost-calculater architecture

> Architecture diagram of the GitHub repository rahulsayz/gcp-cost-calculater, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rahulsayz/gcp-cost-calculater
- Repository: https://github.com/rahulsayz/gcp-cost-calculater

## Overview

##### Project type and purpose
- This is a standalone CLI application (“gcosts”) written in Go.
- Purpose: read a local YAML pricing file + one or more YAML usage files, compute Google Cloud cost estimates, and output a CSV report.
- It also contains auxiliary “build” and “tools” sub-projects to generate the pricing data sources.

##### File structure
- Top level:
- README, LICENSE, CI config (.github/workflows), .gitignore
- pricing.yml (master pricing data)
- folders: build/, gcosts/, tools/, t/, usage/
- build/: scripts (Perl, Go, shell) and mapping files to assemble pricing.yml
- gcosts/: the Go CLI code
- cmd/: command definitions (Cobra commands like “calc”, “help”)
- pricing/: pricing-file loader & lookup logic
- usage/: usage-file parser
- main.go: CLI entrypoint
- tools/: helper scripts to regenerate CSV lists of machine types, regions, etc.
- t/: acceptance / integration tests driving the CLI against sample YAMLs
- usage/: example YAML usage files
- CI pipelines: build-pricing, test, release workflows

##### Extract architecture cues from the README
- The runtime flow is three-step: 1) load pricing.yml, 2) parse usage files, 3) calculate and write CSV.
- No external services or network calls at runtime – everything is local.
- The CLI uses Cobra (implied by the `cmd` folder and typical Go CLI conventions).
- Over 441 automated tests run in CI.

##### Main components
a. Local File System
- pricing.yml (source of unit prices)
- usage/*.yml (user-defined resource usage)
- output: costs.csv
b. gcosts CLI Application
- CLI Entrypoint (main.go)
- Command Router (Cobra)
– ‘calc’ command
– other subcommands (help, about)
- Pricing Loader Module
- Usage Parser Module
- Calculation Engine
- CSV Exporter
c. build/ Subsystem (offline)
- Data Fetch & Mapping Scripts (build/pricing.pl, services.pl, skus.go, etc.)
- Generates or updates pricing.yml
d. tools/ Subsystem (offline)
- CSV generators for machine types, regions, etc.
e. t/ Test Harness
- Sample YAML files + shell scripts
- Validates CLI outputs against expected results
f. CI/CD Pipeline (GitHub Actions)
- build-pricing workflow
- test workflow
- release workflow
g. Users & Environment
- Developer workstation or CI runner
- OS environments (Linux, macOS, Windows)

##### Relationships and dataflows
1. User invokes `gcosts calc --pricing pricing.yml [--dir usage/]`
2. CLI Entrypoint → Command Router
3. Pricing Loader reads pricing.yml → in-memory price table
4. Usage Parser reads each usage/*.yml → in-memory usage objects
5. Calculation Engine: for each usage object: look up unit price → compute cost → accumulate results
6. CSV Exporter writes costs.csv
7. t/ tests simulate steps 1–6 and compare outputs
8. build/ and tools/ scripts run separately to update pricing.yml and CSV reference data
9. CI/CD checks: on push/pr → run tests → build binaries for each platform → publish releases

##### Architectural patterns & design principles
- Modularity: separate modules for CLI routing, data loading, business logic, I/O
- Dependency injection via interfaces (e.g., pricing.Reader, usage.Reader) for testability
- Configuration via files (YAML) only—no environment variables or remote APIs
- Single responsibility per package
- CI as an external orchestrator

##### Technologies and frameworks
- Go (golang)
- Cobra (CLI framework)
- YAML parsing (gopkg.in/yaml.v3 or similar)
- CSV writer (encoding/csv)
- GitHub Actions for CI/CD
- Shell, Perl, Go, SQL for build scripts

##### Summary
- Break the project into logical subsystems: runtime CLI, offline build, offline tools, tests, CI
- File inputs/outputs, modules, and their interactions
- Be detailed: every package or script that contributes materially to the generated pricing data or CLI behavior should be on the canvas.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and environments
    User["Developer / CI Runner"]:::runtime
    User -->|invokes| CLI
    User -->|runs offline| OfflineBuild
    User -->|runs offline| OfflineTools

    %% Runtime CLI Subsystem
    subgraph "Runtime CLI" 
        direction TB
        CLI["gcosts/main.go\n(CLI Entrypoint)"]:::runtime
        Router["cmd/root.go\n(Command Router)"]:::runtime
        CalcCmd["cmd/compute.go\n('calc' Command)"]:::runtime
        PricingLoader["pricing/pricing.go\n(Pricing Loader)"]:::runtime
        UsageParser["usage/files.go & usage/usage.go\n(Usage Parser)"]:::runtime
        CalcEngine["pricing/cost.go\n(Calculation Engine)"]:::runtime
        CSVExporter["CSV Exporter\n(in compute.go)"]:::runtime
        OutputCSV["costs.csv"]:::datastore
    end

    %% Data Stores
    FS_Pricing["pricing.yml\n(Master Pricing Data)"]:::datastore
    FS_Usage["usage/*.yml\n(Example Usage Files)"]:::datastore

    %% Offline Subsystems
    OfflineBuild["build/\n(Pricing Data Generation)"]:::offline
    OfflineTools["tools/\n(Reference CSV Generators)"]:::offline

    %% Test Harness
    TestHarness["t/\n(Test Harness & Sample Inputs)"]:::test

    %% CI/CD
    CI[".github/workflows/\n(GitHub Actions)"]:::ci

    %% Runtime Data Flow
    FS_Pricing -->|load| PricingLoader
    FS_Usage -->|parse| UsageParser
    CLI -->|routes to| Router
    Router -->|executes| CalcCmd
    CalcCmd -->|uses| PricingLoader
    CalcCmd -->|uses| UsageParser
    PricingLoader -->|provides prices| CalcEngine
    UsageParser -->|provides usage| CalcEngine
    CalcEngine -->|sends data to| CSVExporter
    CSVExporter -->|writes| OutputCSV

    %% Offline Data Flow
    OfflineBuild -.->|generates/updates| FS_Pricing
    OfflineTools -.->|generates reference CSVs| tools

    %% Test and CI Orchestration
    CI -->|runs tests| TestHarness
    CI -->|invokes CLI| CLI
    TestHarness -->|validates| OutputCSV
    CI -->|triggers offline builds| OfflineBuild

    %% Click Events
    click FS_Pricing "https://github.com/rahulsayz/gcp-cost-calculater/blob/master/pricing.yml"
    click FS_Usage "https://github.com/rahulsayz/gcp-cost-calculater/blob/master/usage/example.yml"
    click CLI "https://github.com/rahulsayz/gcp-cost-calculater/blob/master/gcosts/main.go"
    click Router "https://github.com/rahulsayz/gcp-cost-calculater/blob/master/gcosts/cmd/root.go"
    click CalcCmd "https://github.com/rahulsayz/gcp-cost-calculater/blob/master/gcosts/cmd/compute.go"
    click PricingLoader "https://github.com/rahulsayz/gcp-cost-calculater/blob/master/gcosts/pricing/pricing.go"
    click UsageParser "https://github.com/rahulsayz/gcp-cost-calculater/blob/master/gcosts/usage/files.go"
    click CalcEngine "https://github.com/rahulsayz/gcp-cost-calculater/blob/master/gcosts/pricing/cost.go"
    click CSVExporter "https://github.com/rahulsayz/gcp-cost-calculater/blob/master/gcosts/cmd/compute.go"
    click OfflineBuild "https://github.com/rahulsayz/gcp-cost-calculater/tree/master/build/"
    click OfflineTools "https://github.com/rahulsayz/gcp-cost-calculater/tree/master/tools/"
    click TestHarness "https://github.com/rahulsayz/gcp-cost-calculater/tree/master/t/"
    click CI "https://github.com/rahulsayz/gcp-cost-calculater/tree/master/.github/workflows/"

    %% Styles
    classDef runtime fill:#a2fba2,stroke:#333,stroke-width:1px
    classDef datastore fill:#a2d2f8,stroke:#333,stroke-width:1px
    classDef offline fill:#cccccc,stroke:#333,stroke-width:1px
    classDef test fill:#f5a5c0,stroke:#333,stroke-width:1px
    classDef ci fill:#f4b942,stroke:#333,stroke-width:1px
```
