# asm-tarek/ai-usage-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/asm-tarek/ai-usage-tracker
- Repository: https://github.com/asm-tarek/ai-usage-tracker

## Overview

AI Usage Tracker is a Chromium extension that reads each signed-in provider’s quota from the provider page, normalizes it, caches it locally, and displays it in an on-page widget or toolbar popup. The main page workflow is site detection → provider strategy selection (internal API with DOM fallback) → cache-aware refresh → widget rendering; options configure display and refresh behavior. The graph preserves the documented popup and options surfaces. Edges reflect shown imports/calls or README statements; sampled excerpts do not expose all provider bridge and popup wiring, so uncertain connections are omitted.

Main entry points: [`src/storage/storage.ts`](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/storage/storage.ts) (Settings and cache), [`src/content/widget-manager.ts`](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/content/widget-manager.ts) (Widget lifecycle), [`src/providers/base-provider.ts`](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/base-provider.ts) (Strategy orchestration), [`src/ui/usage-widget.ts`](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/ui/usage-widget.ts) (Usage widget)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_page["Provider page"]
  node_site["Site detection<br/>[site-detector.ts]"]
  node_lifecycle["Widget lifecycle<br/>[widget-manager.ts]"]
end

subgraph group_usage["Usage retrieval"]
  node_providers["Provider registry"]
  node_provider["Strategy orchestration<br/>[base-provider.ts]"]
  node_chatgpt_adapter["ChatGPT adapter"]
  node_chatgpt_parser["ChatGPT parser<br/>[chatgpt-parser.ts]"]
  node_chatgpt_session["ChatGPT session bridge<br/>[chatgpt-session.ts]"]
  node_chatgpt_injected["ChatGPT usage bridge"]
  node_claude_adapter["Claude adapter"]
  node_claude_parser["Claude parser<br/>[claude-parser.ts]"]
  node_claude_injected["Claude usage bridge"]
  node_dom["DOM fallback<br/>[dom-strategy.ts]"]
  node_normalization["Usage normalization<br/>[normalization.ts]"]
  node_refresh["Refresh and cache policy<br/>[usage-service.ts]"]
end

subgraph group_state["Local state"]
  node_storage[("Settings and cache<br/>[storage.ts]")]
  node_storage_types["Storage schema<br/>[storage-types.ts]"]
end

subgraph group_surfaces["Extension surfaces"]
  node_widget["Usage widget<br/>[usage-widget.ts]"]
  node_display["Display logic<br/>[widget-model.ts]"]
  node_background["Background worker<br/>[service-worker.ts]"]
  node_popup["Toolbar popup<br/>[popup.ts]"]
  node_options["Options page<br/>[options.ts]"]
  node_dates["Time formatting<br/>[dates.ts]"]
end

node_user(("Signed-in user"))
node_claude["Claude page"]
node_chatgpt["ChatGPT page"]

node_user -->|"uses"| node_claude
node_user -->|"uses"| node_chatgpt
node_claude -->|"loads extension on"| node_site
node_chatgpt -->|"loads extension on"| node_site
node_site -->|"starts"| node_lifecycle
node_lifecycle -->|"selects provider"| node_providers
node_lifecycle -->|"refreshes usage"| node_refresh
node_lifecycle -->|"updates"| node_widget
node_lifecycle -->|"reads settings"| node_storage
node_providers -->|"creates"| node_provider
node_provider -->|"tries strategy"| node_chatgpt_adapter
node_provider -->|"tries strategy"| node_claude_adapter
node_provider -->|"tries fallback"| node_dom
node_chatgpt_adapter -->|"parses response"| node_chatgpt_parser
node_claude_adapter -->|"parses response"| node_claude_parser
node_chatgpt_parser -->|"normalizes values"| node_normalization
node_claude_parser -->|"normalizes values"| node_normalization
node_dom -->|"normalizes values"| node_normalization
node_refresh -->|"reads and writes cache"| node_storage
node_chatgpt_injected -->|"uses session"| node_chatgpt_session
node_widget -->|"uses display logic"| node_display
node_widget -->|"formats times"| node_dates
node_popup -->|"reads settings and cache"| node_storage
node_popup -->|"formats times"| node_dates
node_options -->|"reads and writes settings"| node_storage
node_background -->|"uses storage"| node_storage
node_storage -->|"uses schema"| node_storage_types
node_claude -.->|"reads usage"| node_claude_injected
node_chatgpt -.->|"reads usage"| node_chatgpt_injected

click node_site "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/content/site-detector.ts"
click node_lifecycle "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/content/widget-manager.ts"
click node_widget "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/ui/usage-widget.ts"
click node_display "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/ui/widget-model.ts"
click node_providers "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/provider-registry.ts"
click node_provider "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/base-provider.ts"
click node_chatgpt_adapter "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/chatgpt/chatgpt-strategies.ts"
click node_chatgpt_parser "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/chatgpt/chatgpt-parser.ts"
click node_chatgpt_session "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/injected/chatgpt-session.ts"
click node_chatgpt_injected "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/injected/chatgpt-usage-bridge.ts"
click node_claude_adapter "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/claude/claude-strategies.ts"
click node_claude_parser "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/claude/claude-parser.ts"
click node_claude_injected "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/injected/claude-usage-bridge.ts"
click node_dom "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/dom-strategy.ts"
click node_normalization "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/usage/normalization.ts"
click node_refresh "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/usage/usage-service.ts"
click node_storage "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/storage/storage.ts"
click node_storage_types "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/storage/storage-types.ts"
click node_background "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/background/service-worker.ts"
click node_popup "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/popup/popup.ts"
click node_options "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/options/options.ts"
click node_dates "https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/utils/dates.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_site,node_lifecycle,node_user toneBlue
class node_providers,node_provider,node_chatgpt_adapter,node_chatgpt_parser,node_chatgpt_session,node_chatgpt_injected,node_claude_adapter,node_claude_parser,node_claude_injected,node_dom,node_normalization,node_refresh toneAmber
class node_storage,node_storage_types toneMint
class node_widget,node_display,node_background,node_popup,node_options,node_dates toneRose
class node_claude,node_chatgpt toneIndigo
```

## Components

### Provider page

- [Site detection](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/content/site-detector.ts): `src/content/site-detector.ts`
- [Widget lifecycle](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/content/widget-manager.ts): `src/content/widget-manager.ts`

### Usage retrieval

- [Provider registry](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/provider-registry.ts): `src/providers/provider-registry.ts`
- [Strategy orchestration](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/base-provider.ts): `src/providers/base-provider.ts`
- [ChatGPT adapter](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/chatgpt/chatgpt-strategies.ts): `src/providers/chatgpt/chatgpt-strategies.ts`
- [ChatGPT parser](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/chatgpt/chatgpt-parser.ts): `src/providers/chatgpt/chatgpt-parser.ts`
- [ChatGPT session bridge](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/injected/chatgpt-session.ts): `src/injected/chatgpt-session.ts`
- [ChatGPT usage bridge](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/injected/chatgpt-usage-bridge.ts): `src/injected/chatgpt-usage-bridge.ts`
- [Claude adapter](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/claude/claude-strategies.ts): `src/providers/claude/claude-strategies.ts`
- [Claude parser](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/claude/claude-parser.ts): `src/providers/claude/claude-parser.ts`
- [Claude usage bridge](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/injected/claude-usage-bridge.ts): `src/injected/claude-usage-bridge.ts`
- [DOM fallback](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/providers/dom-strategy.ts): `src/providers/dom-strategy.ts`
- [Usage normalization](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/usage/normalization.ts): `src/usage/normalization.ts`
- [Refresh and cache policy](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/usage/usage-service.ts): `src/usage/usage-service.ts`

### Local state

- [Settings and cache](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/storage/storage.ts): `src/storage/storage.ts`
- [Storage schema](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/storage/storage-types.ts): `src/storage/storage-types.ts`

### Extension surfaces

- [Usage widget](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/ui/usage-widget.ts): `src/ui/usage-widget.ts`
- [Display logic](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/ui/widget-model.ts): `src/ui/widget-model.ts`
- [Background worker](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/background/service-worker.ts): `src/background/service-worker.ts`
- [Toolbar popup](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/popup/popup.ts): `src/popup/popup.ts`
- [Options page](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/options/options.ts): `src/options/options.ts`
- [Time formatting](https://github.com/asm-tarek/ai-usage-tracker/blob/main/src/utils/dates.ts): `src/utils/dates.ts`

### Other components

- **Signed-in user**
- **Claude page**
- **ChatGPT page**

## Connections

- Signed-in user → Claude page: uses (evidence: `README.md`)
- Signed-in user → ChatGPT page: uses (evidence: `README.md`)
- Claude page → Site detection: loads extension on (evidence: `README.md`)
- ChatGPT page → Site detection: loads extension on (evidence: `README.md`)
- Site detection → Widget lifecycle: starts
- Widget lifecycle → Provider registry: selects provider (evidence: `src/content/widget-manager.ts`)
- Widget lifecycle → Refresh and cache policy: refreshes usage (evidence: `src/content/widget-manager.ts`)
- Widget lifecycle → Usage widget: updates (evidence: `src/content/widget-manager.ts`)
- Widget lifecycle → Settings and cache: reads settings (evidence: `src/content/widget-manager.ts`)
- Provider registry → Strategy orchestration: creates (evidence: `src/providers/provider-registry.ts`)
- Strategy orchestration → ChatGPT adapter: tries strategy (evidence: `src/providers/chatgpt/chatgpt-provider.ts`)
- Strategy orchestration → Claude adapter: tries strategy (evidence: `src/providers/claude/claude-provider.ts`)
- Strategy orchestration → DOM fallback: tries fallback (evidence: `src/providers/chatgpt/chatgpt-provider.ts`)
- ChatGPT adapter → ChatGPT parser: parses response (evidence: `src/providers/chatgpt/chatgpt-strategies.ts`)
- Claude adapter → Claude parser: parses response (evidence: `src/providers/claude/claude-strategies.ts`)
- ChatGPT parser → Usage normalization: normalizes values (evidence: `src/providers/chatgpt/chatgpt-parser.ts`)
- Claude parser → Usage normalization: normalizes values (evidence: `src/providers/claude/claude-parser.ts`)
- DOM fallback → Usage normalization: normalizes values (evidence: `src/providers/dom-strategy.ts`)
- Refresh and cache policy → Settings and cache: reads and writes cache (evidence: `src/usage/usage-service.ts`)
- ChatGPT usage bridge → ChatGPT session bridge: uses session (evidence: `src/injected/chatgpt-usage-bridge.ts`)
- Usage widget → Display logic: uses display logic (evidence: `src/ui/usage-widget.ts`)
- Usage widget → Time formatting: formats times (evidence: `src/ui/usage-widget.ts`)
- Toolbar popup → Settings and cache: reads settings and cache (evidence: `src/popup/popup.ts`)
- Toolbar popup → Time formatting: formats times (evidence: `src/popup/popup.ts`)
- Options page → Settings and cache: reads and writes settings (evidence: `src/options/options.ts`)
- Background worker → Settings and cache: uses storage (evidence: `src/background/service-worker.ts`)
- Settings and cache → Storage schema: uses schema (evidence: `src/storage/storage.ts`)
- Claude page → Claude usage bridge: reads usage
- ChatGPT page → ChatGPT usage bridge: reads usage
