# willxup/cpa-usage-keeper architecture

> Architecture diagram of the GitHub repository willxup/cpa-usage-keeper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/willxup/cpa-usage-keeper
- Repository: https://github.com/willxup/cpa-usage-keeper

## Overview

CPA Usage Keeper is a standalone persistence and analytics dashboard for CLIProxyAPI. Its main workflow collects CPA usage and configuration data, stores usage in SQLite, and presents usage, cost, request-event, and health analytics in a web dashboard. The README also describes credential/provider monitoring and quota refresh, pricing synchronization, optional backups, community rankings, and read-only CPA API-key views. Connections for backend subsystems are based on documented capabilities and project structure; unsampled implementation details are not asserted.

Main entry points: [`internal/service/usage_service.go`](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/service/usage_service.go) (Usage Services), [`internal/api/router.go`](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/api/router.go) (HTTP API), [`web/src/App.tsx`](https://github.com/willxup/cpa-usage-keeper/blob/main/web/src/App.tsx) (Web Application), [`internal/poller`](https://github.com/willxup/cpa-usage-keeper/tree/main/internal/poller) (Usage Collection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection and Storage"]
  node_server["Keeper Server<br/>[main.go]"]
  node_poller["Usage Collection"]
  node_cpa_client["CPA Client<br/>[client.go]"]
  node_sqlite[("SQLite Persistence")]
  node_backup["Scheduled Backups<br/>[backup.go]"]
  node_api["HTTP API<br/>[router.go]"]
end

subgraph group_analytics["Usage Analytics"]
  node_usage_service["Usage Services<br/>[usage_service.go]"]
  node_activity["Activity Aggregation<br/>[aggregate.go]"]
  node_overview["Overview Analytics<br/>[aggregate.go]"]
  node_latency["Latency Analytics<br/>[aggregate.go]"]
  node_pricing["Model Pricing"]
end

subgraph group_management["Operations and Management"]
  node_quota["Quota Inspection<br/>[service.go]"]
  node_metadata["Metadata Sync<br/>[metadata_sync.go]"]
  node_ranking["Community Ranking<br/>[service.go]"]
  node_auth["Authentication<br/>[session.go]"]
end

subgraph group_web["Web Experience"]
  node_app["Web Application<br/>[App.tsx]"]
  node_usage_page["Usage Dashboard<br/>[UsagePage.tsx]"]
  node_key_pages["API Key Views"]
  node_web_api["API Client<br/>[api.ts]"]
  node_embed["CPAMC Embed<br/>[cpamcEmbed.ts]"]
end

node_cpa(("CLIProxyAPI"))
node_browser(("Dashboard User"))

node_cpa -->|"provides usage"| node_poller
node_poller -.->|"collects data"| node_cpa_client
node_poller -->|"persists usage"| node_sqlite
node_server -.->|"serves routes"| node_api
node_api -.->|"serves usage"| node_usage_service
node_usage_service -.->|"reads usage"| node_sqlite
node_backup -->|"backs up"| node_sqlite
node_usage_service -.->|"aggregates activity"| node_activity
node_usage_service -.->|"builds overview"| node_overview
node_usage_service -.->|"analyzes latency"| node_latency
node_usage_service -->|"estimates cost"| node_pricing
node_api -->|"exposes refresh"| node_quota
node_metadata -->|"syncs configuration"| node_cpa
node_api -->|"exposes rankings"| node_ranking
node_api -->|"protects access"| node_auth
node_browser -->|"uses dashboard"| node_app
node_app -.->|"authenticates"| node_auth
node_app -->|"routes to"| node_usage_page
node_app -->|"routes to"| node_key_pages
node_usage_page -->|"requests analytics"| node_web_api
node_key_pages -.->|"requests key views"| node_web_api
node_web_api -->|"calls endpoints"| node_api
node_app -->|"supports embedding"| node_embed

click node_server "https://github.com/willxup/cpa-usage-keeper/blob/main/cmd/server/main.go"
click node_poller "https://github.com/willxup/cpa-usage-keeper/tree/main/internal/poller"
click node_cpa_client "https://github.com/willxup/cpa-usage-keeper/blob/main/internal/cpa/client.go"
click node_sqlite "https://github.com/willxup/cpa-usage-keeper/tree/main/internal/repository"
click node_backup "https://github.com/willxup/cpa-usage-keeper/blob/main/internal/backup/backup.go"
click node_api "https://github.com/willxup/cpa-usage-keeper/blob/main/internal/api/router.go"
click node_usage_service "https://github.com/willxup/cpa-usage-keeper/blob/main/internal/service/usage_service.go"
click node_activity "https://github.com/willxup/cpa-usage-keeper/blob/main/internal/activity/aggregate.go"
click node_overview "https://github.com/willxup/cpa-usage-keeper/blob/main/internal/overview/aggregate.go"
click node_latency "https://github.com/willxup/cpa-usage-keeper/blob/main/internal/latency/aggregate.go"
click node_pricing "https://github.com/willxup/cpa-usage-keeper/tree/main/internal/pricing"
click node_quota "https://github.com/willxup/cpa-usage-keeper/blob/main/internal/quota/service.go"
click node_metadata "https://github.com/willxup/cpa-usage-keeper/blob/main/internal/service/metadata_sync.go"
click node_ranking "https://github.com/willxup/cpa-usage-keeper/blob/main/internal/ranking/service.go"
click node_auth "https://github.com/willxup/cpa-usage-keeper/blob/main/internal/auth/session.go"
click node_app "https://github.com/willxup/cpa-usage-keeper/blob/main/web/src/App.tsx"
click node_usage_page "https://github.com/willxup/cpa-usage-keeper/blob/main/web/src/pages/UsagePage.tsx"
click node_key_pages "https://github.com/willxup/cpa-usage-keeper/blob/main/web/src/pages/KeyOverviewPage.tsx"
click node_web_api "https://github.com/willxup/cpa-usage-keeper/blob/main/web/src/lib/api.ts"
click node_embed "https://github.com/willxup/cpa-usage-keeper/blob/main/web/src/embed/cpamcEmbed.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_server,node_poller,node_cpa_client,node_sqlite,node_backup,node_api,node_browser toneBlue
class node_usage_service,node_activity,node_overview,node_latency,node_pricing toneAmber
class node_quota,node_metadata,node_ranking,node_auth,node_cpa toneMint
class node_app,node_usage_page,node_key_pages,node_web_api,node_embed toneRose
```

## Components

### Collection and Storage

- [Keeper Server](https://github.com/willxup/cpa-usage-keeper/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [Usage Collection](https://github.com/willxup/cpa-usage-keeper/tree/main/internal/poller): `internal/poller`
- [CPA Client](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/cpa/client.go): `internal/cpa/client.go`
- [SQLite Persistence](https://github.com/willxup/cpa-usage-keeper/tree/main/internal/repository): `internal/repository`
- [Scheduled Backups](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/backup/backup.go): `internal/backup/backup.go`
- [HTTP API](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/api/router.go): `internal/api/router.go`

### Usage Analytics

- [Usage Services](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/service/usage_service.go): `internal/service/usage_service.go`
- [Activity Aggregation](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/activity/aggregate.go): `internal/activity/aggregate.go`
- [Overview Analytics](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/overview/aggregate.go): `internal/overview/aggregate.go`
- [Latency Analytics](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/latency/aggregate.go): `internal/latency/aggregate.go`
- [Model Pricing](https://github.com/willxup/cpa-usage-keeper/tree/main/internal/pricing): `internal/pricing`

### Operations and Management

- [Quota Inspection](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/quota/service.go): `internal/quota/service.go`
- [Metadata Sync](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/service/metadata_sync.go): `internal/service/metadata_sync.go`
- [Community Ranking](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/ranking/service.go): `internal/ranking/service.go`
- [Authentication](https://github.com/willxup/cpa-usage-keeper/blob/main/internal/auth/session.go): `internal/auth/session.go`

### Web Experience

- [Web Application](https://github.com/willxup/cpa-usage-keeper/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Usage Dashboard](https://github.com/willxup/cpa-usage-keeper/blob/main/web/src/pages/UsagePage.tsx): `web/src/pages/UsagePage.tsx`
- [API Key Views](https://github.com/willxup/cpa-usage-keeper/blob/main/web/src/pages/KeyOverviewPage.tsx): `web/src/pages/KeyOverviewPage.tsx`
- [API Client](https://github.com/willxup/cpa-usage-keeper/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [CPAMC Embed](https://github.com/willxup/cpa-usage-keeper/blob/main/web/src/embed/cpamcEmbed.ts): `web/src/embed/cpamcEmbed.ts`

### Other components

- **CLIProxyAPI**
- **Dashboard User**

## Connections

- CLIProxyAPI → Usage Collection: provides usage (evidence: `README.md`)
- Usage Collection → CPA Client: collects data
- Usage Collection → SQLite Persistence: persists usage (evidence: `README.md`)
- Keeper Server → HTTP API: serves routes
- HTTP API → Usage Services: serves usage
- Usage Services → SQLite Persistence: reads usage
- Scheduled Backups → SQLite Persistence: backs up (evidence: `README.md`)
- Usage Services → Activity Aggregation: aggregates activity
- Usage Services → Overview Analytics: builds overview
- Usage Services → Latency Analytics: analyzes latency
- Usage Services → Model Pricing: estimates cost (evidence: `README.md`)
- HTTP API → Quota Inspection: exposes refresh (evidence: `README.md`)
- Metadata Sync → CLIProxyAPI: syncs configuration (evidence: `README.md`)
- HTTP API → Community Ranking: exposes rankings (evidence: `README.md`)
- HTTP API → Authentication: protects access (evidence: `README.md`)
- Dashboard User → Web Application: uses dashboard (evidence: `README.md`)
- Web Application → Authentication: authenticates
- Web Application → Usage Dashboard: routes to (evidence: `web/src/App.tsx`)
- Web Application → API Key Views: routes to (evidence: `web/src/App.tsx`)
- Usage Dashboard → API Client: requests analytics (evidence: `web/src/pages/UsagePage.tsx`)
- API Key Views → API Client: requests key views
- API Client → HTTP API: calls endpoints (evidence: `README.md`)
- Web Application → CPAMC Embed: supports embedding (evidence: `web/src/App.tsx`)