# desmondlee95700/aiusage architecture

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

- Interactive diagram: https://gitdiagram.com/desmondlee95700/aiusage
- Repository: https://github.com/desmondlee95700/aiusage

## Overview

AIUsage is a native macOS menu-bar app for viewing local account and quota data from Antigravity, ChatGPT/Codex, and Claude. The principal workflow starts at the menu-bar controller, refreshes provider discovery and quota state through QuotaService, then presents the selected providers’ usage in a popover and status item. The README also documents provider filtering, account/plan details, reset windows, and Liquid Glass styling. Arrows reflect the excerpts, source index references, or README; unsampled provider-protocol details are represented only where documented.

Main entry points: [`Sources/Services/QuotaService.swift`](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/QuotaService.swift) (Quota Coordinator), [`Sources/Views/MainUsageView.swift`](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/MainUsageView.swift) (Usage Popover), [`Sources/MenuBar/StatusBarController.swift`](https://github.com/desmondlee95700/aiusage/blob/main/Sources/MenuBar/StatusBarController.swift) (Menu Bar Controller), [`Sources/Services/CodexDiscovery.swift`](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/CodexDiscovery.swift) (Codex Discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App Entry"]
  node_main["App Startup<br/>[main.swift]"]
  node_menubar["Menu Bar Controller"]
end

subgraph group_services["Discovery &amp; Quotas"]
  node_quota["Quota Coordinator<br/>[QuotaService.swift]"]
  node_antigravity_discovery["Antigravity Discovery"]
  node_codex_discovery["Codex Discovery"]
  node_claude_discovery["Claude Discovery"]
  node_codex_service["Codex Quota Client<br/>[CodexService.swift]"]
  node_claude_service["Claude Quota Client"]
  node_gemini_service["Antigravity Quota Client<br/>[QuotaService.swift]"]
  node_models["Quota Data Models<br/>[QuotaModels.swift]"]
end

subgraph group_presentation["Usage Presentation"]
  node_main_view["Usage Popover"]
  node_provider_filter["Provider Filter"]
  node_chatgpt_card["ChatGPT Quota Card"]
  node_claude_card["Claude Quota Card"]
  node_antigravity_card["Antigravity Quota Card"]
  node_credits_card["Credits Card"]
  node_plan_card["Plan &amp; Account Card<br/>[PlanCardView.swift]"]
  node_progress["Progress Rings"]
  node_icons["Provider Icons"]
  node_version["Version Display<br/>[AppVersion.swift]"]
end

subgraph group_design["Appearance"]
  node_glass_observer["Glass Preference Observer"]
  node_glass_style["Liquid Glass Styling<br/>[LiquidGlass.swift]"]
end

node_user(("Mac User"))
node_antigravity_app{{"Antigravity Runtime"}}
node_chatgpt_app{{"ChatGPT Runtime"}}
node_claude_app{{"Claude Desktop"}}

node_user -->|"opens menu"| node_menubar
node_main -->|"starts"| node_menubar
node_menubar -->|"refreshes state"| node_quota
node_menubar -->|"shows popover"| node_main_view
node_menubar -->|"renders status"| node_icons
node_menubar -->|"shows version"| node_version
node_quota -->|"discovers runtime"| node_antigravity_discovery
node_quota -->|"discovers runtime"| node_codex_discovery
node_quota -->|"discovers runtime"| node_claude_discovery
node_quota -->|"fetches quotas"| node_codex_service
node_quota -->|"fetches quotas"| node_claude_service
node_quota -->|"refreshes quotas"| node_gemini_service
node_antigravity_discovery -.->|"probes locally"| node_antigravity_app
node_codex_discovery -->|"finds runtime"| node_chatgpt_app
node_claude_discovery -->|"discovers app"| node_claude_app
node_codex_service -->|"resolves runtime"| node_codex_discovery
node_quota -.->|"holds quota state"| node_models
node_main_view -->|"reads usage state"| node_quota
node_main_view -->|"shows filter"| node_provider_filter
node_provider_filter -->|"changes selection"| node_quota
node_main_view -->|"renders provider"| node_chatgpt_card
node_main_view -->|"renders provider"| node_claude_card
node_main_view -->|"renders provider"| node_antigravity_card
node_main_view -->|"renders account details"| node_plan_card
node_chatgpt_card -->|"shows limits"| node_progress
node_claude_card -->|"shows limits"| node_progress
node_antigravity_card -->|"shows limits"| node_progress
node_main_view -->|"reads intensity"| node_glass_observer
node_glass_observer -->|"informs styling"| node_glass_style

click node_main "https://github.com/desmondlee95700/aiusage/blob/main/Sources/main.swift"
click node_menubar "https://github.com/desmondlee95700/aiusage/blob/main/Sources/MenuBar/StatusBarController.swift"
click node_quota "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/QuotaService.swift"
click node_antigravity_discovery "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/ProcessDiscovery.swift"
click node_codex_discovery "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/CodexDiscovery.swift"
click node_claude_discovery "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/ClaudeDiscovery.swift"
click node_codex_service "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/CodexService.swift"
click node_claude_service "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/ClaudeService.swift"
click node_gemini_service "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/QuotaService.swift"
click node_models "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Models/QuotaModels.swift"
click node_main_view "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/MainUsageView.swift"
click node_provider_filter "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/ProviderFocusSubmenuView.swift"
click node_chatgpt_card "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/ChatGPTQuotaCardView.swift"
click node_claude_card "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/ClaudeQuotaCardView.swift"
click node_antigravity_card "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/QuotaCardView.swift"
click node_credits_card "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/CreditsCardView.swift"
click node_plan_card "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/PlanCardView.swift"
click node_progress "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/CircularProgressView.swift"
click node_glass_observer "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/LiquidGlassObserver.swift"
click node_glass_style "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/LiquidGlass.swift"
click node_icons "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/AppIconHelper.swift"
click node_version "https://github.com/desmondlee95700/aiusage/blob/main/Sources/Models/AppVersion.swift"

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_menubar,node_user toneBlue
class node_quota,node_antigravity_discovery,node_codex_discovery,node_claude_discovery,node_codex_service,node_claude_service,node_gemini_service,node_models toneAmber
class node_main_view,node_provider_filter,node_chatgpt_card,node_claude_card,node_antigravity_card,node_credits_card,node_plan_card,node_progress,node_icons,node_version toneMint
class node_glass_observer,node_glass_style toneRose
class node_antigravity_app,node_chatgpt_app,node_claude_app toneIndigo
```

## Components

### App Entry

- [App Startup](https://github.com/desmondlee95700/aiusage/blob/main/Sources/main.swift): `Sources/main.swift`
- [Menu Bar Controller](https://github.com/desmondlee95700/aiusage/blob/main/Sources/MenuBar/StatusBarController.swift): `Sources/MenuBar/StatusBarController.swift`

### Discovery & Quotas

- [Quota Coordinator](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/QuotaService.swift): `Sources/Services/QuotaService.swift`
- [Antigravity Discovery](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/ProcessDiscovery.swift): `Sources/Services/ProcessDiscovery.swift`
- [Codex Discovery](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/CodexDiscovery.swift): `Sources/Services/CodexDiscovery.swift`
- [Claude Discovery](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/ClaudeDiscovery.swift): `Sources/Services/ClaudeDiscovery.swift`
- [Codex Quota Client](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/CodexService.swift): `Sources/Services/CodexService.swift`
- [Claude Quota Client](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/ClaudeService.swift): `Sources/Services/ClaudeService.swift`
- [Antigravity Quota Client](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/QuotaService.swift): `Sources/Services/QuotaService.swift`
- [Quota Data Models](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Models/QuotaModels.swift): `Sources/Models/QuotaModels.swift`

### Usage Presentation

- [Usage Popover](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/MainUsageView.swift): `Sources/Views/MainUsageView.swift`
- [Provider Filter](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/ProviderFocusSubmenuView.swift): `Sources/Views/ProviderFocusSubmenuView.swift`
- [ChatGPT Quota Card](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/ChatGPTQuotaCardView.swift): `Sources/Views/ChatGPTQuotaCardView.swift`
- [Claude Quota Card](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/ClaudeQuotaCardView.swift): `Sources/Views/ClaudeQuotaCardView.swift`
- [Antigravity Quota Card](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/QuotaCardView.swift): `Sources/Views/QuotaCardView.swift`
- [Credits Card](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/CreditsCardView.swift): `Sources/Views/CreditsCardView.swift`
- [Plan & Account Card](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/PlanCardView.swift): `Sources/Views/PlanCardView.swift`
- [Progress Rings](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/CircularProgressView.swift): `Sources/Views/CircularProgressView.swift`
- [Provider Icons](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/AppIconHelper.swift): `Sources/Views/AppIconHelper.swift`
- [Version Display](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Models/AppVersion.swift): `Sources/Models/AppVersion.swift`

### Appearance

- [Glass Preference Observer](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Services/LiquidGlassObserver.swift): `Sources/Services/LiquidGlassObserver.swift`
- [Liquid Glass Styling](https://github.com/desmondlee95700/aiusage/blob/main/Sources/Views/LiquidGlass.swift): `Sources/Views/LiquidGlass.swift`

### Other components

- **Mac User**
- **Antigravity Runtime**
- **ChatGPT Runtime**
- **Claude Desktop**

## Connections

- Mac User → Menu Bar Controller: opens menu (evidence: `README.md`)
- App Startup → Menu Bar Controller: starts (evidence: `Sources/main.swift`)
- Menu Bar Controller → Quota Coordinator: refreshes state (evidence: `Sources/MenuBar/StatusBarController.swift`)
- Menu Bar Controller → Usage Popover: shows popover (evidence: `Sources/MenuBar/StatusBarController.swift`)
- Menu Bar Controller → Provider Icons: renders status (evidence: `Sources/MenuBar/StatusBarController.swift`)
- Menu Bar Controller → Version Display: shows version (evidence: `Sources/MenuBar/StatusBarController.swift`)
- Quota Coordinator → Antigravity Discovery: discovers runtime (evidence: `Sources/Services/QuotaService.swift`)
- Quota Coordinator → Codex Discovery: discovers runtime (evidence: `Sources/Services/QuotaService.swift`)
- Quota Coordinator → Claude Discovery: discovers runtime (evidence: `Sources/Services/QuotaService.swift`)
- Quota Coordinator → Codex Quota Client: fetches quotas (evidence: `Sources/Services/QuotaService.swift`)
- Quota Coordinator → Claude Quota Client: fetches quotas (evidence: `Sources/Services/QuotaService.swift`)
- Quota Coordinator → Antigravity Quota Client: refreshes quotas (evidence: `Sources/Services/QuotaService.swift`)
- Antigravity Discovery → Antigravity Runtime: probes locally
- Codex Discovery → ChatGPT Runtime: finds runtime (evidence: `Sources/Services/CodexDiscovery.swift`)
- Claude Discovery → Claude Desktop: discovers app (evidence: `Sources/Services/ClaudeDiscovery.swift`)
- Codex Quota Client → Codex Discovery: resolves runtime (evidence: `Sources/Services/CodexService.swift`)
- Quota Coordinator → Quota Data Models: holds quota state
- Usage Popover → Quota Coordinator: reads usage state (evidence: `Sources/Views/MainUsageView.swift`)
- Usage Popover → Provider Filter: shows filter (evidence: `Sources/Views/MainUsageView.swift`)
- Provider Filter → Quota Coordinator: changes selection (evidence: `Sources/Views/ProviderFocusSubmenuView.swift`)
- Usage Popover → ChatGPT Quota Card: renders provider (evidence: `Sources/Views/MainUsageView.swift`)
- Usage Popover → Claude Quota Card: renders provider (evidence: `Sources/Views/MainUsageView.swift`)
- Usage Popover → Antigravity Quota Card: renders provider (evidence: `Sources/Views/MainUsageView.swift`)
- Usage Popover → Plan & Account Card: renders account details (evidence: `Sources/Views/MainUsageView.swift`)
- ChatGPT Quota Card → Progress Rings: shows limits (evidence: `Sources/Views/ChatGPTQuotaCardView.swift`)
- Claude Quota Card → Progress Rings: shows limits (evidence: `Sources/Views/ClaudeQuotaCardView.swift`)
- Antigravity Quota Card → Progress Rings: shows limits (evidence: `Sources/Views/QuotaCardView.swift`)
- Usage Popover → Glass Preference Observer: reads intensity (evidence: `Sources/Views/MainUsageView.swift`)
- Glass Preference Observer → Liquid Glass Styling: informs styling (evidence: `Sources/Views/LiquidGlass.swift`)