# junhoyeo/tokscale architecture

> Architecture diagram of the GitHub repository junhoyeo/tokscale, 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/junhoyeo/tokscale
- Repository: https://github.com/junhoyeo/tokscale

## Overview

Tokscale combines a local Rust CLI that reads AI-agent usage, analyzes token and cost data, and presents it in a terminal UI with a web service for sharing submissions. The main workflow runs from local agent data through provider-specific session parsing and aggregation to reports or an optional leaderboard submission; the web application then supports public profiles, rankings, and groups. Pricing lookup and live provider-usage queries are additional capabilities. Some frontend and CLI subsystems are represented by their exact directories because their implementation was not sampled; those links rely on README documentation where noted.

Main entry points: [`packages/frontend/src/lib/db`](https://github.com/junhoyeo/tokscale/tree/main/packages/frontend/src/lib/db) (Platform database), [`crates/tokscale-cli/src/main.rs`](https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-cli/src/main.rs) (CLI commands), [`packages/frontend/src/app/api/submit/route.ts`](https://github.com/junhoyeo/tokscale/blob/main/packages/frontend/src/app/api/submit/route.ts) (Submission API), [`crates/tokscale-core/src/pricing`](https://github.com/junhoyeo/tokscale/tree/main/crates/tokscale-core/src/pricing) (Model pricing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_entry["CLI commands<br/>[main.rs]"]
  node_import["Import and reports"]
  node_termui["Terminal dashboard"]
  node_providerusage["Provider usage<br/>[mod.rs]"]
  node_submitcli["Data submission<br/>[autosubmit.rs]"]
  node_auth["CLI authentication<br/>[auth.rs]"]
end

subgraph group_core["Usage analysis"]
  node_providerlogs["Provider sessions"]
  node_sessionize["Session analysis<br/>[sessionize.rs]"]
  node_aggregate["Usage aggregation<br/>[aggregator.rs]"]
end

subgraph group_web["Web platform"]
  node_websubmit["Submission API<br/>[route.ts]"]
  node_webdb[("Platform database")]
  node_profiles["Public profiles"]
  node_leaderboard["Leaderboards"]
  node_groups["Usage groups"]
end

subgraph group_pricing["Pricing and providers"]
  node_pricing["Model pricing"]
  node_pricingcache[("Pricing cache<br/>[cache.rs]")]
end

node_user(("CLI user"))
node_agentdata[("Agent data")]
node_pricingservice["Pricing sources"]

node_user -->|"runs commands"| node_entry
node_agentdata -->|"provides usage logs"| node_providerlogs
node_entry -->|"fetches live usage"| node_providerusage
node_providerusage -.->|"shows usage"| node_termui
node_entry -->|"routes commands"| node_import
node_providerlogs -.->|"parses sessions"| node_sessionize
node_sessionize -.->|"groups usage"| node_aggregate
node_aggregate -.->|"feeds dashboard"| node_termui
node_user -->|"submits data"| node_submitcli
node_submitcli -->|"posts submission"| node_websubmit
node_auth -.->|"authorizes requests"| node_websubmit
node_websubmit -->|"writes submissions"| node_webdb
node_webdb -.->|"supplies profile data"| node_profiles
node_webdb -.->|"supplies rankings"| node_leaderboard
node_webdb -.->|"stores group data"| node_groups
node_pricing -->|"caches rates"| node_pricingcache
node_pricing -->|"fetches model rates"| node_pricingservice

click node_entry "https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-cli/src/main.rs"
click node_import "https://github.com/junhoyeo/tokscale/tree/main/crates/tokscale-cli/src/commands"
click node_termui "https://github.com/junhoyeo/tokscale/tree/main/crates/tokscale-cli/src/tui"
click node_providerusage "https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-cli/src/commands/usage/mod.rs"
click node_providerlogs "https://github.com/junhoyeo/tokscale/tree/main/crates/tokscale-core/src/sessions"
click node_sessionize "https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-core/src/sessionize.rs"
click node_aggregate "https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-core/src/aggregator.rs"
click node_submitcli "https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-cli/src/commands/autosubmit.rs"
click node_auth "https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-cli/src/auth.rs"
click node_websubmit "https://github.com/junhoyeo/tokscale/blob/main/packages/frontend/src/app/api/submit/route.ts"
click node_webdb "https://github.com/junhoyeo/tokscale/tree/main/packages/frontend/src/lib/db"
click node_profiles "https://github.com/junhoyeo/tokscale/tree/main/packages/frontend/src/app/u/%5Busername%5D"
click node_leaderboard "https://github.com/junhoyeo/tokscale/tree/main/packages/frontend/src/app/(main)/leaderboard"
click node_groups "https://github.com/junhoyeo/tokscale/tree/main/packages/frontend/src/app/(main)/groups"
click node_pricing "https://github.com/junhoyeo/tokscale/tree/main/crates/tokscale-core/src/pricing"
click node_pricingcache "https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-core/src/pricing/cache.rs"

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_entry,node_import,node_termui,node_providerusage,node_submitcli,node_auth,node_user toneBlue
class node_providerlogs,node_sessionize,node_aggregate,node_agentdata toneAmber
class node_websubmit,node_webdb,node_profiles,node_leaderboard,node_groups toneMint
class node_pricing,node_pricingcache toneRose
class node_pricingservice toneIndigo
```

## Components

### CLI workflow

- [CLI commands](https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-cli/src/main.rs): `crates/tokscale-cli/src/main.rs`
- [Import and reports](https://github.com/junhoyeo/tokscale/tree/main/crates/tokscale-cli/src/commands): `crates/tokscale-cli/src/commands`
- [Terminal dashboard](https://github.com/junhoyeo/tokscale/tree/main/crates/tokscale-cli/src/tui): `crates/tokscale-cli/src/tui`
- [Provider usage](https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-cli/src/commands/usage/mod.rs): `crates/tokscale-cli/src/commands/usage/mod.rs`
- [Data submission](https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-cli/src/commands/autosubmit.rs): `crates/tokscale-cli/src/commands/autosubmit.rs`
- [CLI authentication](https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-cli/src/auth.rs): `crates/tokscale-cli/src/auth.rs`

### Usage analysis

- [Provider sessions](https://github.com/junhoyeo/tokscale/tree/main/crates/tokscale-core/src/sessions): `crates/tokscale-core/src/sessions`
- [Session analysis](https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-core/src/sessionize.rs): `crates/tokscale-core/src/sessionize.rs`
- [Usage aggregation](https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-core/src/aggregator.rs): `crates/tokscale-core/src/aggregator.rs`

### Web platform

- [Submission API](https://github.com/junhoyeo/tokscale/blob/main/packages/frontend/src/app/api/submit/route.ts): `packages/frontend/src/app/api/submit/route.ts`
- [Platform database](https://github.com/junhoyeo/tokscale/tree/main/packages/frontend/src/lib/db): `packages/frontend/src/lib/db`
- [Public profiles](https://github.com/junhoyeo/tokscale/tree/main/packages/frontend/src/app/u/%5Busername%5D): `packages/frontend/src/app/u/[username]`
- [Leaderboards](https://github.com/junhoyeo/tokscale/tree/main/packages/frontend/src/app/(main)/leaderboard): `packages/frontend/src/app/(main)/leaderboard`
- [Usage groups](https://github.com/junhoyeo/tokscale/tree/main/packages/frontend/src/app/(main)/groups): `packages/frontend/src/app/(main)/groups`

### Pricing and providers

- [Model pricing](https://github.com/junhoyeo/tokscale/tree/main/crates/tokscale-core/src/pricing): `crates/tokscale-core/src/pricing`
- [Pricing cache](https://github.com/junhoyeo/tokscale/blob/main/crates/tokscale-core/src/pricing/cache.rs): `crates/tokscale-core/src/pricing/cache.rs`

### Other components

- **CLI user**
- **Agent data**
- **Pricing sources**

## Connections

- CLI user → CLI commands: runs commands (evidence: `README.md`)
- Agent data → Provider sessions: provides usage logs (evidence: `README.md`)
- CLI commands → Provider usage: fetches live usage (evidence: `crates/tokscale-cli/src/commands/usage/mod.rs`)
- Provider usage → Terminal dashboard: shows usage (evidence: `crates/tokscale-cli/src/commands/usage/mod.rs`)
- CLI commands → Import and reports: routes commands (evidence: `crates/tokscale-cli/src/main.rs`)
- Provider sessions → Session analysis: parses sessions (evidence: `crates/tokscale-core/src/sessionize.rs`)
- Session analysis → Usage aggregation: groups usage
- Usage aggregation → Terminal dashboard: feeds dashboard
- CLI user → Data submission: submits data (evidence: `README.md`)
- Data submission → Submission API: posts submission
- CLI authentication → Submission API: authorizes requests
- Submission API → Platform database: writes submissions (evidence: `packages/frontend/src/app/api/submit/route.ts`)
- Platform database → Public profiles: supplies profile data
- Platform database → Leaderboards: supplies rankings
- Platform database → Usage groups: stores group data
- Model pricing → Pricing cache: caches rates (evidence: `crates/tokscale-core/src/pricing/litellm.rs`)
- Model pricing → Pricing sources: fetches model rates (evidence: `crates/tokscale-core/src/pricing/litellm.rs`)