{
  "repo": "tidbcloud/billing-bills-verify",
  "binary": "billing-bills-verify",
  "binary_path": "cmd/main.go",
  "downstream_services": {
    "gcp-sts": {
      "clients": ["googleapis.V1betaService"],
      "target_service": "Google Cloud STS (sts.googleapis.com)",
      "purpose": "Exchange EKS OIDC token for GCP federated token (Workload Identity)",
      "trigger": "When GOOGLE_APPLICATION_CREDENTIALS == \"\" && USE_DEFAULT_GCP_CREDENTIAL == \"false\""
    },
    "gcp-iamcredentials": {
      "clients": ["googleapis.ImpersonateTokenSource"],
      "target_service": "Google Cloud IAM Credentials (iamcredentials.googleapis.com)",
      "purpose": "Generate access token by impersonating target service account",
      "trigger": "After STS token exchange"
    },
    "gcp-bigquery": {
      "clients": ["BigQueryClient"],
      "target_service": "Google Cloud BigQuery",
      "purpose": "Query GCP billing data for verification",
      "trigger": "After authentication"
    }
  },
  "dependencies": {
    "HealthService.Ping": {
      "infrastructure": {},
      "services": []
    },
    "HealthService.Version": {
      "infrastructure": {},
      "services": []
    },
    "VerifyService.VerifyNetworkBill": {
      "infrastructure": {
        "gcp_bigquery": {
          "conditions": [
            "Always during network bill verification"
          ],
          "operations": [
            {
              "operation": "QUERY",
              "trigger": "Execute verification SQL against billing data",
              "conditions": [
                "VerifyNetworkBill handler is invoked"
              ],
              "implementation": "BigQueryClient.ExecQuery()",
              "notes": [
                "Current implementation uses placeholder WITH Roster CTE and does not yet query the configured billing table.",
                "Table and BillProject parameters are reserved for future verification logic."
              ]
            }
          ]
        }
      },
      "services": [
        {
          "name": "gcp-sts",
          "operation_type": "http_post",
          "target_service": "Google Cloud STS",
          "target_interface": "POST /v1beta/token",
          "conditions": ["GOOGLE_APPLICATION_CREDENTIALS == \"\" && USE_DEFAULT_GCP_CREDENTIAL == \"false\""],
          "operations": [
            {
              "operation": "STS Token Exchange",
              "trigger": "Exchange EKS OIDC token for GCP federated token",
              "implementation": "sts.googleapis.com (pkg/provider/gcp/googleapis/sts-gen.go:276)"
            }
          ]
        },
        {
          "name": "gcp-iamcredentials",
          "operation_type": "http_post",
          "target_service": "Google Cloud IAM Credentials",
          "target_interface": "POST /v1/projects/-/serviceAccounts/{sa}:generateAccessToken",
          "conditions": ["After STS token exchange"],
          "operations": [
            {
              "operation": "IAM Impersonation",
              "trigger": "Impersonate target service account",
              "implementation": "iamcredentials.googleapis.com (pkg/provider/gcp/googleapis/impersonate.go:95)"
            }
          ]
        },
        {
          "name": "gcp-bigquery",
          "operation_type": "http_post",
          "target_service": "Google Cloud BigQuery API",
          "target_interface": "POST /v2/projects/{projectId}/queries",
          "conditions": ["Always"],
          "operations": [
            {
              "operation": "BigQuery Query",
              "trigger": "Execute verification SQL against billing data",
              "conditions": ["Always"],
              "implementation": "gcp.BigQueryClient.Query()"
            }
          ]
        }
      ]
    }
  },
  "external_dependencies": {
    "gcp": {
      "services": [
        {
          "name": "BigQuery",
          "purpose": "Query billing export data",
          "auth_method": "Workload Identity (K8s IAM) or GOOGLE_APPLICATION_CREDENTIALS"
        },
        {
          "name": "STS",
          "purpose": "Token exchange for Workload Identity",
          "auth_method": "EKS OIDC token projection"
        },
        {
          "name": "IAM Credentials",
          "purpose": "Service account impersonation",
          "auth_method": "STS federated token"
        }
      ],
      "config": {
        "provider_project_id": "GCP project for BigQuery client",
        "location": "BigQuery location (e.g., US, EU)",
        "bigquery_table_name": "Billing export table name (for future verification logic)",
        "bill_project_id": "Project that generates bills (for future verification logic)",
        "gcp_workload_identity_audience": "Workload Identity pool provider",
        "gcp_impersonate_sa": "Target service account to impersonate"
      }
    },
    "sentry": {
      "purpose": "Error reporting and monitoring",
      "optional": true
    }
  },
  "infrastructure_summary": {
    "gcp_bigquery": {
      "tables": ["gcp_billing_export_v1_*"],
      "operations": ["QUERY"],
      "purpose": "GCP billing data verification source"
    }
  },
  "data_models": {
    "Request": {
      "description": "Verification request payload",
      "fields": {
        "tenant_id": "Tenant identifier",
        "project_id": "Project identifier (optional)",
        "start_time": "Query start time",
        "end_time": "Query end time",
        "data_version": "Data version for cost plan"
      }
    },
    "Response": {
      "description": "Standard API response",
      "fields": {
        "code": "HTTP status code",
        "err_message": "Error message if any",
        "data": "Response data"
      }
    },
    "Bill": {
      "description": "Billing data structure (embeds Request)",
      "fields": {
        "Request": "Embedded request fields (tenant_id, project_id, etc.)",
        "Data": "Array of Item objects"
      }
    },
    "Item": {
      "description": "Individual billing item within Bill",
      "fields": {
        "Labels": "Resource labels (tenant_id, project_id, cluster_id, component_id, usedby, servicetype, provider)",
        "Amount": "Resource amount",
        "Unit": "Unit of measurement",
        "Cost": "Cost in currency",
        "ResourceType": "Type of resource",
        "ResourceSubtype": "Subtype (cross_az, cross_region, internet, lb)",
        "DataVersion": "Data version for cost plan",
        "ServiceName": "Name of the service",
        "Description": "Description of the billing item",
        "Location": "Geographic location",
        "StartTime": "Item start time",
        "EndTime": "Item end time"
      }
    }
  },
  "statistics": {
    "total_downstream_services": 3,
    "total_external_dependencies": 2,
    "dependencies_documented": 3
  },
  "notes": [
    "Lightweight verification service for GCP billing data",
    "Primary dependencies: GCP STS → IAM Credentials → BigQuery (Workload Identity auth chain)",
    "Uses Workload Identity for GCP authentication in Kubernetes (sts.googleapis.com + iamcredentials.googleapis.com)",
    "Supports extensible verification logic via template pattern (CreateBigquerySQL)",
    "CURRENT IMPLEMENTATION NOTE: VerifyNetworkBill uses placeholder SQL (WITH Roster CTE), does not query configured billing table",
    "Configuration params (Table, BillProject) are prepared for future verification logic, not currently used",
    "Verification logic: SQL query returns 0 rows = verification passed",
    "Planned extensions: BillingService, Backup, CDC verification"
  ]
}