# jimakosk46/quota-usage architecture

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

- Interactive diagram: https://gitdiagram.com/jimakosk46/quota-usage
- Repository: https://github.com/jimakosk46/quota-usage

## Overview

quota-usage is a macOS CLI for viewing Codex and Claude subscription quota windows across discovered and registered accounts. Its main workflow inventories accounts, selects them, collects live provider data or reads cached results, then presents a dashboard or snapshot in human or JSON form. Separate capabilities handle account setup, diagnostics, uninstall, and checkout self-updates. The graph follows the documented product flow and sampled collection wiring; some CLI dispatch and account-management internals are not shown in the excerpts, so those links rely on README statements or are omitted.

Main entry points: [`src/collect.ts`](https://github.com/jimakosk46/quota-usage/blob/main/src/collect.ts) (Collection orchestrator), [`src/cli.ts`](https://github.com/jimakosk46/quota-usage/blob/main/src/cli.ts) (Usage CLI), [`src/accounts.ts`](https://github.com/jimakosk46/quota-usage/blob/main/src/accounts.ts) (Account management), [`src/tui.ts`](https://github.com/jimakosk46/quota-usage/blob/main/src/tui.ts) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and output"]
  node_cli["Usage CLI<br/>[cli.ts]"]
  node_tui["Dashboard<br/>[tui.ts]"]
  node_human["Human output<br/>[render-human.ts]"]
  node_json["JSON output<br/>[render-json.ts]"]
end

subgraph group_accounts["Account lifecycle"]
  node_config[("Config store<br/>[config.ts]")]
  node_accounts_cmd["Account management<br/>[accounts.ts]"]
  node_discovery["Account discovery<br/>[discovery.ts]"]
  node_doctor["Diagnostics<br/>[doctor.ts]"]
  node_uninstall["Uninstall<br/>[uninstall.ts]"]
end

subgraph group_collection["Quota collection"]
  node_collect["Collection orchestrator<br/>[collect.ts]"]
  node_selectors["Account selection<br/>[selectors.ts]"]
  node_codex["Codex adapter<br/>[codex.ts]"]
  node_claude["Claude live adapter<br/>[claude-live.ts]"]
  node_claude_cache["Claude cache helper<br/>[claude-cache.ts]"]
  node_cache[("Usage cache<br/>[cache.ts]")]
  node_statusline["Status-line collector"]
end

subgraph group_runtime["Runtime support"]
  node_auto_update["Update trigger<br/>[auto-update.ts]"]
  node_update["Checkout updater<br/>[update-checkout.ts]"]
  node_processes["Process manager<br/>[processes.ts]"]
  node_paths["Path safeguards<br/>[paths.ts]"]
  node_executable["Executable resolver<br/>[executable.ts]"]
  node_duration["Duration utilities<br/>[duration.ts]"]
  node_errors["Error model<br/>[errors.ts]"]
  node_types["Domain types<br/>[types.ts]"]
end

node_user(("User"))
node_vendor["Codex / Claude CLIs"]
node_checkout["Git origin"]

node_user -->|"runs commands"| node_cli
node_cli -->|"starts collection"| node_collect
node_cli -->|"manages accounts"| node_accounts_cmd
node_cli -->|"runs diagnostics"| node_doctor
node_cli -->|"uninstalls tool"| node_uninstall
node_cli -->|"opens dashboard"| node_tui
node_cli -->|"prints snapshot"| node_human
node_cli -->|"prints JSON"| node_json
node_cli -->|"starts update"| node_auto_update
node_tui -->|"refreshes data"| node_collect
node_tui -->|"renders view"| node_human
node_collect -->|"discovers accounts"| node_discovery
node_collect -->|"selects accounts"| node_selectors
node_collect -->|"collects Codex"| node_codex
node_collect -->|"collects Claude"| node_claude
node_collect -->|"reads and writes"| node_cache
node_collect -->|"uses settings"| node_config
node_codex -->|"queries Codex"| node_vendor
node_claude -->|"queries Claude"| node_vendor
node_accounts_cmd -->|"saves registrations"| node_config
node_accounts_cmd -->|"launches login"| node_vendor
node_accounts_cmd -->|"installs collector"| node_statusline
node_auto_update -->|"requests update"| node_update
node_update -->|"fast-forwards from"| node_checkout
node_collect -->|"resolves providers"| node_executable
node_collect -->|"tracks subprocesses"| node_processes
node_accounts_cmd -->|"checks managed paths"| node_paths
node_config -->|"uses app paths"| node_paths
node_collect -->|"parses cache age"| node_duration
node_collect -->|"normalizes failures"| node_errors
node_collect -->|"produces results"| node_types
node_claude_cache -.->|"supports cache flow"| node_cache

click node_cli "https://github.com/jimakosk46/quota-usage/blob/main/src/cli.ts"
click node_tui "https://github.com/jimakosk46/quota-usage/blob/main/src/tui.ts"
click node_human "https://github.com/jimakosk46/quota-usage/blob/main/src/render-human.ts"
click node_json "https://github.com/jimakosk46/quota-usage/blob/main/src/render-json.ts"
click node_config "https://github.com/jimakosk46/quota-usage/blob/main/src/config.ts"
click node_accounts_cmd "https://github.com/jimakosk46/quota-usage/blob/main/src/accounts.ts"
click node_discovery "https://github.com/jimakosk46/quota-usage/blob/main/src/discovery.ts"
click node_doctor "https://github.com/jimakosk46/quota-usage/blob/main/src/doctor.ts"
click node_uninstall "https://github.com/jimakosk46/quota-usage/blob/main/src/uninstall.ts"
click node_collect "https://github.com/jimakosk46/quota-usage/blob/main/src/collect.ts"
click node_selectors "https://github.com/jimakosk46/quota-usage/blob/main/src/selectors.ts"
click node_codex "https://github.com/jimakosk46/quota-usage/blob/main/src/providers/codex.ts"
click node_claude "https://github.com/jimakosk46/quota-usage/blob/main/src/providers/claude-live.ts"
click node_claude_cache "https://github.com/jimakosk46/quota-usage/blob/main/src/providers/claude-cache.ts"
click node_cache "https://github.com/jimakosk46/quota-usage/blob/main/src/cache.ts"
click node_statusline "https://github.com/jimakosk46/quota-usage/blob/main/src/statusline-helper.ts"
click node_auto_update "https://github.com/jimakosk46/quota-usage/blob/main/src/auto-update.ts"
click node_update "https://github.com/jimakosk46/quota-usage/blob/main/src/update-checkout.ts"
click node_processes "https://github.com/jimakosk46/quota-usage/blob/main/src/processes.ts"
click node_paths "https://github.com/jimakosk46/quota-usage/blob/main/src/paths.ts"
click node_executable "https://github.com/jimakosk46/quota-usage/blob/main/src/executable.ts"
click node_duration "https://github.com/jimakosk46/quota-usage/blob/main/src/duration.ts"
click node_errors "https://github.com/jimakosk46/quota-usage/blob/main/src/errors.ts"
click node_types "https://github.com/jimakosk46/quota-usage/blob/main/src/types.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_cli,node_tui,node_human,node_json,node_user toneBlue
class node_config,node_accounts_cmd,node_discovery,node_doctor,node_uninstall toneAmber
class node_collect,node_selectors,node_codex,node_claude,node_claude_cache,node_cache,node_statusline toneMint
class node_auto_update,node_update,node_processes,node_paths,node_executable,node_duration,node_errors,node_types toneRose
class node_vendor,node_checkout toneIndigo
```

## Components

### CLI and output

- [Usage CLI](https://github.com/jimakosk46/quota-usage/blob/main/src/cli.ts): `src/cli.ts`
- [Dashboard](https://github.com/jimakosk46/quota-usage/blob/main/src/tui.ts): `src/tui.ts`
- [Human output](https://github.com/jimakosk46/quota-usage/blob/main/src/render-human.ts): `src/render-human.ts`
- [JSON output](https://github.com/jimakosk46/quota-usage/blob/main/src/render-json.ts): `src/render-json.ts`

### Account lifecycle

- [Config store](https://github.com/jimakosk46/quota-usage/blob/main/src/config.ts): `src/config.ts`
- [Account management](https://github.com/jimakosk46/quota-usage/blob/main/src/accounts.ts): `src/accounts.ts`
- [Account discovery](https://github.com/jimakosk46/quota-usage/blob/main/src/discovery.ts): `src/discovery.ts`
- [Diagnostics](https://github.com/jimakosk46/quota-usage/blob/main/src/doctor.ts): `src/doctor.ts`
- [Uninstall](https://github.com/jimakosk46/quota-usage/blob/main/src/uninstall.ts): `src/uninstall.ts`

### Quota collection

- [Collection orchestrator](https://github.com/jimakosk46/quota-usage/blob/main/src/collect.ts): `src/collect.ts`
- [Account selection](https://github.com/jimakosk46/quota-usage/blob/main/src/selectors.ts): `src/selectors.ts`
- [Codex adapter](https://github.com/jimakosk46/quota-usage/blob/main/src/providers/codex.ts): `src/providers/codex.ts`
- [Claude live adapter](https://github.com/jimakosk46/quota-usage/blob/main/src/providers/claude-live.ts): `src/providers/claude-live.ts`
- [Claude cache helper](https://github.com/jimakosk46/quota-usage/blob/main/src/providers/claude-cache.ts): `src/providers/claude-cache.ts`
- [Usage cache](https://github.com/jimakosk46/quota-usage/blob/main/src/cache.ts): `src/cache.ts`
- [Status-line collector](https://github.com/jimakosk46/quota-usage/blob/main/src/statusline-helper.ts): `src/statusline-helper.ts`

### Runtime support

- [Update trigger](https://github.com/jimakosk46/quota-usage/blob/main/src/auto-update.ts): `src/auto-update.ts`
- [Checkout updater](https://github.com/jimakosk46/quota-usage/blob/main/src/update-checkout.ts): `src/update-checkout.ts`
- [Process manager](https://github.com/jimakosk46/quota-usage/blob/main/src/processes.ts): `src/processes.ts`
- [Path safeguards](https://github.com/jimakosk46/quota-usage/blob/main/src/paths.ts): `src/paths.ts`
- [Executable resolver](https://github.com/jimakosk46/quota-usage/blob/main/src/executable.ts): `src/executable.ts`
- [Duration utilities](https://github.com/jimakosk46/quota-usage/blob/main/src/duration.ts): `src/duration.ts`
- [Error model](https://github.com/jimakosk46/quota-usage/blob/main/src/errors.ts): `src/errors.ts`
- [Domain types](https://github.com/jimakosk46/quota-usage/blob/main/src/types.ts): `src/types.ts`

### Other components

- **User**
- **Codex / Claude CLIs**
- **Git origin**

## Connections

- User → Usage CLI: runs commands (evidence: `README.md`)
- Usage CLI → Collection orchestrator: starts collection (evidence: `README.md`)
- Usage CLI → Account management: manages accounts (evidence: `README.md`)
- Usage CLI → Diagnostics: runs diagnostics (evidence: `README.md`)
- Usage CLI → Uninstall: uninstalls tool (evidence: `README.md`)
- Usage CLI → Dashboard: opens dashboard (evidence: `README.md`)
- Usage CLI → Human output: prints snapshot (evidence: `README.md`)
- Usage CLI → JSON output: prints JSON (evidence: `README.md`)
- Usage CLI → Update trigger: starts update (evidence: `README.md`)
- Dashboard → Collection orchestrator: refreshes data (evidence: `src/tui.ts`)
- Dashboard → Human output: renders view (evidence: `src/tui.ts`)
- Collection orchestrator → Account discovery: discovers accounts (evidence: `src/collect.ts`)
- Collection orchestrator → Account selection: selects accounts (evidence: `src/collect.ts`)
- Collection orchestrator → Codex adapter: collects Codex (evidence: `src/collect.ts`)
- Collection orchestrator → Claude live adapter: collects Claude (evidence: `src/collect.ts`)
- Collection orchestrator → Usage cache: reads and writes (evidence: `src/collect.ts`)
- Collection orchestrator → Config store: uses settings (evidence: `src/collect.ts`)
- Codex adapter → Codex / Claude CLIs: queries Codex (evidence: `README.md`)
- Claude live adapter → Codex / Claude CLIs: queries Claude (evidence: `README.md`)
- Account management → Config store: saves registrations (evidence: `README.md`)
- Account management → Codex / Claude CLIs: launches login (evidence: `README.md`)
- Account management → Status-line collector: installs collector (evidence: `README.md`)
- Update trigger → Checkout updater: requests update (evidence: `src/auto-update.ts`)
- Checkout updater → Git origin: fast-forwards from (evidence: `README.md`)
- Collection orchestrator → Executable resolver: resolves providers (evidence: `src/collect.ts`)
- Collection orchestrator → Process manager: tracks subprocesses (evidence: `src/collect.ts`)
- Account management → Path safeguards: checks managed paths (evidence: `src/accounts.ts`)
- Config store → Path safeguards: uses app paths (evidence: `src/config.ts`)
- Collection orchestrator → Duration utilities: parses cache age (evidence: `src/collect.ts`)
- Collection orchestrator → Error model: normalizes failures (evidence: `src/collect.ts`)
- Collection orchestrator → Domain types: produces results (evidence: `src/collect.ts`)
- Claude cache helper → Usage cache: supports cache flow
