# ishitasequeira/pricetag-metering architecture

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

- Interactive diagram: https://gitdiagram.com/ishitasequeira/pricetag-metering
- Repository: https://github.com/ishitasequeira/pricetag-metering

## Overview

PriceTag Metering Service is a development backend for gateway token metering, balance checks, usage aggregation, and operator management. Its principal flow is gateway usage-event ingestion into a PostgreSQL ledger, followed by balance and dashboard/team-usage reads; rollups accelerate aggregate panels. The broader service also supports authentication, quotas and model-access policy, partner administration, pricing, and gateway/cluster integrations. The excerpts show selected calls and startup wiring; other relationships below are included only where documented in the README or evidenced by the source index.

Main entry points: [`internal/storage/postgres.go`](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/storage/postgres.go) (Ledger and storage), [`cmd/main.go`](https://github.com/ishitasequeira/pricetag-metering/blob/main/cmd/main.go) (HTTP service), [`internal/handler/events.go`](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/events.go) (Usage ingestion), [`internal/handler/auth.go`](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/auth.go) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Service runtime"]
  node_main["HTTP service<br/>[main.go]"]
  node_metrics["Service metrics<br/>[metrics.go]"]
end

subgraph group_metering["Metering and reads"]
  node_events["Usage ingestion<br/>[events.go]"]
  node_entitlements["Balance checks<br/>[entitlements.go]"]
  node_dashboard["Usage dashboard<br/>[dashboard.go]"]
  node_teamusage["Team usage<br/>[usage_report.go]"]
  node_rollups["Usage rollups<br/>[rollups.go]"]
  node_store[("Ledger and storage<br/>[postgres.go]")]
  node_pricing["Pricing<br/>[pricing.go]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Authentication<br/>[auth.go]"]
  node_oidc["OIDC login<br/>[oidc.go]"]
  node_modelaccess["Model access policy<br/>[model_access.go]"]
end

subgraph group_operations["Administration"]
  node_partnerusers["Partner users<br/>[partner_users.go]"]
  node_partnerorg["Partner organizations<br/>[partner_org.go]"]
  node_managementkeys["Management keys<br/>[management_keys.go]"]
  node_admin["Admin operations<br/>[admin.go]"]
  node_quota["Quota policy<br/>[quota.go]"]
end

subgraph group_integrations["Platform integrations"]
  node_maas["MaaS API<br/>[client.go]"]
  node_k8s["Kubernetes API<br/>[client.go]"]
end

node_gateway(("Inference gateway"))

node_gateway -->|"posts events"| node_events
node_gateway -->|"checks balance"| node_entitlements
node_main -.->|"serves routes"| node_events
node_main -.->|"serves routes"| node_dashboard
node_main -.->|"configures"| node_auth
node_main -->|"initializes"| node_store
node_main -->|"starts backfill"| node_rollups
node_events -.->|"records usage"| node_store
node_entitlements -.->|"reads balance"| node_store
node_dashboard -.->|"reads usage"| node_store
node_teamusage -.->|"reads usage"| node_store
node_rollups -->|"aggregates ledger"| node_store
node_modelaccess -->|"reads and writes"| node_store
node_partnerusers -->|"reads users"| node_store
node_partnerorg -.->|"uses directory"| node_store
node_managementkeys -.->|"manages keys"| node_maas
node_admin -->|"manages cluster"| node_k8s
node_admin -->|"searches keys"| node_maas
node_quota -.->|"persists policy"| node_store
node_main -->|"records requests"| node_metrics
node_main -.->|"configures pricing"| node_pricing
node_auth -.->|"checks identity"| node_store
node_oidc -.->|"supports login"| node_auth

click node_main "https://github.com/ishitasequeira/pricetag-metering/blob/main/cmd/main.go"
click node_events "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/events.go"
click node_entitlements "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/entitlements.go"
click node_dashboard "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/dashboard.go"
click node_teamusage "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/usage_report.go"
click node_rollups "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/storage/rollups.go"
click node_store "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/storage/postgres.go"
click node_auth "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/auth.go"
click node_oidc "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/oidc.go"
click node_modelaccess "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/model_access.go"
click node_partnerusers "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/partner_users.go"
click node_partnerorg "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/partner_org.go"
click node_managementkeys "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/management_keys.go"
click node_admin "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/admin.go"
click node_quota "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/storage/quota.go"
click node_pricing "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/pricing/pricing.go"
click node_maas "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/maasapi/client.go"
click node_k8s "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/k8s/client.go"
click node_metrics "https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/metrics/metrics.go"

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_main,node_metrics toneBlue
class node_events,node_entitlements,node_dashboard,node_teamusage,node_rollups,node_store,node_pricing toneAmber
class node_auth,node_oidc,node_modelaccess toneMint
class node_partnerusers,node_partnerorg,node_managementkeys,node_admin,node_quota toneRose
class node_maas,node_k8s,node_gateway toneIndigo
```

## Components

### Service runtime

- [HTTP service](https://github.com/ishitasequeira/pricetag-metering/blob/main/cmd/main.go): `cmd/main.go`
- [Service metrics](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`

### Metering and reads

- [Usage ingestion](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/events.go): `internal/handler/events.go`
- [Balance checks](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/entitlements.go): `internal/handler/entitlements.go`
- [Usage dashboard](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/dashboard.go): `internal/handler/dashboard.go`
- [Team usage](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/usage_report.go): `internal/handler/usage_report.go`
- [Usage rollups](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/storage/rollups.go): `internal/storage/rollups.go`
- [Ledger and storage](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/storage/postgres.go): `internal/storage/postgres.go`
- [Pricing](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/pricing/pricing.go): `internal/pricing/pricing.go`

### Identity and access

- [Authentication](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/auth.go): `internal/handler/auth.go`
- [OIDC login](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/oidc.go): `internal/handler/oidc.go`
- [Model access policy](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/model_access.go): `internal/handler/model_access.go`

### Administration

- [Partner users](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/partner_users.go): `internal/handler/partner_users.go`
- [Partner organizations](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/partner_org.go): `internal/handler/partner_org.go`
- [Management keys](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/management_keys.go): `internal/handler/management_keys.go`
- [Admin operations](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/handler/admin.go): `internal/handler/admin.go`
- [Quota policy](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/storage/quota.go): `internal/storage/quota.go`

### Platform integrations

- [MaaS API](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/maasapi/client.go): `internal/maasapi/client.go`
- [Kubernetes API](https://github.com/ishitasequeira/pricetag-metering/blob/main/internal/k8s/client.go): `internal/k8s/client.go`

### Other components

- **Inference gateway**

## Connections

- Inference gateway → Usage ingestion: posts events (evidence: `README.md`)
- Inference gateway → Balance checks: checks balance (evidence: `README.md`)
- HTTP service → Usage ingestion: serves routes
- HTTP service → Usage dashboard: serves routes
- HTTP service → Authentication: configures
- HTTP service → Ledger and storage: initializes (evidence: `cmd/main.go`)
- HTTP service → Usage rollups: starts backfill (evidence: `cmd/main.go`)
- Usage ingestion → Ledger and storage: records usage
- Balance checks → Ledger and storage: reads balance
- Usage dashboard → Ledger and storage: reads usage
- Team usage → Ledger and storage: reads usage
- Usage rollups → Ledger and storage: aggregates ledger (evidence: `README.md`)
- Model access policy → Ledger and storage: reads and writes (evidence: `internal/handler/model_access.go`)
- Partner users → Ledger and storage: reads users (evidence: `internal/handler/partner_users.go`)
- Partner organizations → Ledger and storage: uses directory
- Management keys → MaaS API: manages keys
- Admin operations → Kubernetes API: manages cluster (evidence: `internal/handler/admin.go`)
- Admin operations → MaaS API: searches keys (evidence: `internal/handler/admin.go`)
- Quota policy → Ledger and storage: persists policy
- HTTP service → Service metrics: records requests (evidence: `cmd/main.go`)
- HTTP service → Pricing: configures pricing
- Authentication → Ledger and storage: checks identity
- OIDC login → Authentication: supports login
