# mm7894215/tokentracker architecture

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

## Overview

Token Tracker is a local-first usage and cost tracker for AI coding tools, delivered through a cross-platform CLI, dashboard, and native desktop apps. The main workflow detects tool data, syncs and serves it locally, then presents usage insights in the dashboard. Documented side capabilities include skills browsing, achievements, desktop pets, widgets, and optional cloud features. Source excerpts are partial, so edges without direct excerpt evidence rely on README statements; uncertain internal calls are omitted.

Main entry points: [`dashboard/src/App.jsx`](https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/App.jsx) (Dashboard UI), [`dashboard/src/pages/DashboardPage.jsx`](https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/pages/DashboardPage.jsx) (Usage views), [`src/commands/sync.js`](https://github.com/mm7894215/tokentracker/blob/main/src/commands/sync.js) (Usage sync), [`src/cli.js`](https://github.com/mm7894215/tokentracker/blob/main/src/cli.js) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Collection and serving"]
  node_cli["CLI entry<br/>[cli.js]"]
  node_tooldata["Tool usage data"]
  node_hooks["Tool hooks<br/>[init.js]"]
  node_sync["Usage sync<br/>[sync.js]"]
  node_server["Local server<br/>[serve.js]"]
end

subgraph group_dashboard["Dashboard experience"]
  node_dashboardui["Dashboard UI<br/>[App.jsx]"]
  node_usageapi["Usage API<br/>[api.ts]"]
  node_usageviews["Usage views<br/>[DashboardPage.jsx]"]
  node_skills["Skills browser<br/>[SkillsPage.jsx]"]
end

subgraph group_capabilities["Insights and extras"]
  node_analysis["Usage analysis"]
  node_achievements["Achievements"]
  node_pet["Desktop pet<br/>[PetPage.jsx]"]
  node_widgets["Native widgets"]
end

subgraph group_desktop["Desktop clients"]
  node_macapp["macOS app"]
  node_winapp["Windows app"]
  node_linuxapp["Linux app<br/>[main.rs]"]
end

subgraph group_cloud["Cloud services"]
  node_auth["Dashboard auth"]
  node_cloudapi["Cloud API"]
end

node_developer(("Developer"))

node_developer -->|"runs"| node_cli
node_cli -->|"installs"| node_hooks
node_tooldata -->|"provides logs"| node_sync
node_hooks -->|"enable collection"| node_sync
node_cli -->|"starts sync"| node_sync
node_sync -->|"serves locally"| node_server
node_server -->|"opens dashboard"| node_dashboardui
node_dashboardui -->|"requests data"| node_usageapi
node_usageapi -.->|"supplies usage"| node_usageviews
node_usageviews -->|"presents insights"| node_analysis
node_dashboardui -->|"offers browsing"| node_skills
node_usageviews -->|"supports tracks"| node_achievements
node_usageviews -->|"drives companion"| node_pet
node_usageviews -->|"publishes snapshots"| node_widgets
node_developer -->|"uses desktop app"| node_macapp
node_developer -->|"uses desktop app"| node_winapp
node_developer -->|"uses desktop app"| node_linuxapp
node_macapp -->|"hosts dashboard"| node_dashboardui
node_winapp -->|"hosts dashboard"| node_dashboardui
node_linuxapp -->|"hosts dashboard"| node_dashboardui
node_dashboardui -->|"provides sign-in"| node_auth
node_auth -.->|"optional cloud access"| node_cloudapi

click node_cli "https://github.com/mm7894215/tokentracker/blob/main/src/cli.js"
click node_hooks "https://github.com/mm7894215/tokentracker/blob/main/src/commands/init.js"
click node_sync "https://github.com/mm7894215/tokentracker/blob/main/src/commands/sync.js"
click node_server "https://github.com/mm7894215/tokentracker/blob/main/src/commands/serve.js"
click node_dashboardui "https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/App.jsx"
click node_usageapi "https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/lib/api.ts"
click node_usageviews "https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/pages/DashboardPage.jsx"
click node_skills "https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/pages/SkillsPage.jsx"
click node_analysis "https://github.com/mm7894215/tokentracker/tree/main/dashboard/src/ui/dashboard/components"
click node_achievements "https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/pages/AchievementsPage.jsx"
click node_pet "https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/pages/PetPage.jsx"
click node_widgets "https://github.com/mm7894215/tokentracker/tree/main/TokenTrackerBar/TokenTrackerWidget/Widgets"
click node_macapp "https://github.com/mm7894215/tokentracker/blob/main/TokenTrackerBar/TokenTrackerBar/Services/StatusBarController.swift"
click node_winapp "https://github.com/mm7894215/tokentracker/blob/main/TokenTrackerWin/TrayApplicationContext.cs"
click node_linuxapp "https://github.com/mm7894215/tokentracker/blob/main/TokenTrackerLinux/src-tauri/src/main.rs"
click node_auth "https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/contexts/InsforgeAuthContext.jsx"
click node_cloudapi "https://github.com/mm7894215/tokentracker/blob/main/dashboard/edge-patches/tokentracker-ingest.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_tooldata,node_hooks,node_sync,node_server toneBlue
class node_dashboardui,node_usageapi,node_usageviews,node_skills toneAmber
class node_analysis,node_achievements,node_pet,node_widgets toneMint
class node_macapp,node_winapp,node_linuxapp toneRose
class node_auth,node_cloudapi,node_developer toneIndigo
```

## Components

### Collection and serving

- [CLI entry](https://github.com/mm7894215/tokentracker/blob/main/src/cli.js): `src/cli.js`
- **Tool usage data**
- [Tool hooks](https://github.com/mm7894215/tokentracker/blob/main/src/commands/init.js): `src/commands/init.js`
- [Usage sync](https://github.com/mm7894215/tokentracker/blob/main/src/commands/sync.js): `src/commands/sync.js`
- [Local server](https://github.com/mm7894215/tokentracker/blob/main/src/commands/serve.js): `src/commands/serve.js`

### Dashboard experience

- [Dashboard UI](https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/App.jsx): `dashboard/src/App.jsx`
- [Usage API](https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/lib/api.ts): `dashboard/src/lib/api.ts`
- [Usage views](https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/pages/DashboardPage.jsx): `dashboard/src/pages/DashboardPage.jsx`
- [Skills browser](https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/pages/SkillsPage.jsx): `dashboard/src/pages/SkillsPage.jsx`

### Insights and extras

- [Usage analysis](https://github.com/mm7894215/tokentracker/tree/main/dashboard/src/ui/dashboard/components): `dashboard/src/ui/dashboard/components`
- [Achievements](https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/pages/AchievementsPage.jsx): `dashboard/src/pages/AchievementsPage.jsx`
- [Desktop pet](https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/pages/PetPage.jsx): `dashboard/src/pages/PetPage.jsx`
- [Native widgets](https://github.com/mm7894215/tokentracker/tree/main/TokenTrackerBar/TokenTrackerWidget/Widgets): `TokenTrackerBar/TokenTrackerWidget/Widgets`

### Desktop clients

- [macOS app](https://github.com/mm7894215/tokentracker/blob/main/TokenTrackerBar/TokenTrackerBar/Services/StatusBarController.swift): `TokenTrackerBar/TokenTrackerBar/Services/StatusBarController.swift`
- [Windows app](https://github.com/mm7894215/tokentracker/blob/main/TokenTrackerWin/TrayApplicationContext.cs): `TokenTrackerWin/TrayApplicationContext.cs`
- [Linux app](https://github.com/mm7894215/tokentracker/blob/main/TokenTrackerLinux/src-tauri/src/main.rs): `TokenTrackerLinux/src-tauri/src/main.rs`

### Cloud services

- [Dashboard auth](https://github.com/mm7894215/tokentracker/blob/main/dashboard/src/contexts/InsforgeAuthContext.jsx): `dashboard/src/contexts/InsforgeAuthContext.jsx`
- [Cloud API](https://github.com/mm7894215/tokentracker/blob/main/dashboard/edge-patches/tokentracker-ingest.ts): `dashboard/edge-patches/tokentracker-ingest.ts`

### Other components

- **Developer**

## Connections

- Developer → CLI entry: runs (evidence: `README.md`)
- CLI entry → Tool hooks: installs (evidence: `README.md`)
- Tool usage data → Usage sync: provides logs (evidence: `README.md`)
- Tool hooks → Usage sync: enable collection (evidence: `README.md`)
- CLI entry → Usage sync: starts sync (evidence: `README.md`)
- Usage sync → Local server: serves locally (evidence: `README.md`)
- Local server → Dashboard UI: opens dashboard (evidence: `README.md`)
- Dashboard UI → Usage API: requests data (evidence: `dashboard/src/App.jsx`)
- Usage API → Usage views: supplies usage
- Usage views → Usage analysis: presents insights (evidence: `README.md`)
- Dashboard UI → Skills browser: offers browsing (evidence: `README.md`)
- Usage views → Achievements: supports tracks (evidence: `README.md`)
- Usage views → Desktop pet: drives companion (evidence: `README.md`)
- Usage views → Native widgets: publishes snapshots
- Developer → macOS app: uses desktop app (evidence: `README.md`)
- Developer → Windows app: uses desktop app (evidence: `README.md`)
- Developer → Linux app: uses desktop app (evidence: `README.md`)
- macOS app → Dashboard UI: hosts dashboard
- Windows app → Dashboard UI: hosts dashboard (evidence: `README.md`)
- Linux app → Dashboard UI: hosts dashboard (evidence: `README.md`)
- Dashboard UI → Dashboard auth: provides sign-in (evidence: `dashboard/src/App.jsx`)
- Dashboard auth → Cloud API: optional cloud access
