# nanako0129/tokenbar architecture

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

- Interactive diagram: https://gitdiagram.com/nanako0129/tokenbar
- Repository: https://github.com/nanako0129/tokenbar

## Overview

Syrtis is a local-first macOS menu-bar monitor that reads AI coding-tool usage, derives usage and quota summaries, and presents them in a dashboard and menu-bar indicators. The main workflow runs from the user opening the status item through refresh and Rust-backed aggregation into Swift dashboard views. The README documents broad reporting, quota, chart, settings, and update capabilities; their exact internal wiring is not fully sampled, so subsystem-level links are limited to documented behavior. Rust source paths and the Swift FFI bridge implementation are not sampled.

Main entry points: [`crates/tb_core_ffi/src/lib.rs`](https://github.com/nanako0129/tokenbar/blob/main/crates/tb_core_ffi/src/lib.rs) (Rust FFI Core), [`Sources/Syrtis/DashboardModel.swift`](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/DashboardModel.swift) (Dashboard Model), [`Sources/Syrtis/UsageDataSource.swift`](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/UsageDataSource.swift) (Usage Data Source), [`Sources/Syrtis/PopoverView.swift`](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/PopoverView.swift) (Dashboard Panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Menu Bar Shell"]
  node_status["Status Item"]
  node_app["App Startup<br/>[main.swift]"]
  node_clienttray["Quota Menu Items<br/>[ClientTray.swift]"]
  node_updater["App Updates"]
end

subgraph group_ingest["Usage Collection"]
  node_source["Usage Data Source"]
end

subgraph group_core["Reports and Quotas"]
  node_rustffi["Rust FFI Core<br/>[lib.rs]"]
  node_reports["Usage Reports<br/>[TBCore.swift]"]
  node_quotas["Quota Reports"]
end

subgraph group_ui["Dashboard and Settings"]
  node_dashboardmodel["Dashboard Model"]
  node_popover["Dashboard Panel<br/>[PopoverView.swift]"]
  node_views["Report Views<br/>[ViewSwitch.swift]"]
  node_charts["Usage Charts"]
  node_graph3d["3D Activity Graph"]
  node_settings["Settings Window"]
end

subgraph group_integrations["External Services"]
  node_sessionlogs["Tool Session Logs"]
  node_provider{{"Quota Providers"}}
  node_keychain[("macOS Keychain")]
  node_sparkle{{"Sparkle Service"}}
end

node_person(("User"))

node_person -->|"opens dashboard"| node_status
node_status -->|"activates app"| node_app
node_app -->|"starts refresh"| node_source
node_source -->|"reads logs"| node_sessionlogs
node_source -->|"requests parsing"| node_rustffi
node_rustffi -->|"returns data"| node_reports
node_rustffi -->|"fetches quotas"| node_provider
node_rustffi -.->|"reads credentials"| node_keychain
node_reports -->|"supplies reports"| node_dashboardmodel
node_quotas -->|"supplies quota data"| node_dashboardmodel
node_dashboardmodel -->|"provides state"| node_popover
node_popover -->|"selects lens"| node_views
node_views -->|"renders usage"| node_charts
node_charts -->|"renders activity"| node_graph3d
node_popover -->|"opens settings"| node_settings
node_dashboardmodel -->|"updates indicators"| node_clienttray
node_person -->|"requests update"| node_updater
node_updater -->|"checks releases"| node_sparkle

click node_status "https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/StatusItemController.swift"
click node_app "https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/main.swift"
click node_source "https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/UsageDataSource.swift"
click node_rustffi "https://github.com/nanako0129/tokenbar/blob/main/crates/tb_core_ffi/src/lib.rs"
click node_reports "https://github.com/nanako0129/tokenbar/blob/main/Sources/TokenBarCore/TBCore.swift"
click node_quotas "https://github.com/nanako0129/tokenbar/blob/main/Sources/TokenBarCore/QuotaResolver.swift"
click node_dashboardmodel "https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/DashboardModel.swift"
click node_popover "https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/PopoverView.swift"
click node_views "https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/Views/ViewSwitch.swift"
click node_charts "https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/Views/UsageChartCard.swift"
click node_graph3d "https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/Charts/ContributionGraph3D.swift"
click node_settings "https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/SettingsWindowController.swift"
click node_clienttray "https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/ClientTray.swift"
click node_updater "https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/UpdaterService.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_status,node_app,node_clienttray,node_updater,node_person toneBlue
class node_source toneAmber
class node_rustffi,node_reports,node_quotas toneMint
class node_dashboardmodel,node_popover,node_views,node_charts,node_graph3d,node_settings toneRose
class node_sessionlogs,node_provider,node_keychain,node_sparkle toneIndigo
```

## Components

### Menu Bar Shell

- [Status Item](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/StatusItemController.swift): `Sources/Syrtis/StatusItemController.swift`
- [App Startup](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/main.swift): `Sources/Syrtis/main.swift`
- [Quota Menu Items](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/ClientTray.swift): `Sources/Syrtis/ClientTray.swift`
- [App Updates](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/UpdaterService.swift): `Sources/Syrtis/UpdaterService.swift`

### Usage Collection

- [Usage Data Source](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/UsageDataSource.swift): `Sources/Syrtis/UsageDataSource.swift`

### Reports and Quotas

- [Rust FFI Core](https://github.com/nanako0129/tokenbar/blob/main/crates/tb_core_ffi/src/lib.rs): `crates/tb_core_ffi/src/lib.rs`
- [Usage Reports](https://github.com/nanako0129/tokenbar/blob/main/Sources/TokenBarCore/TBCore.swift): `Sources/TokenBarCore/TBCore.swift`
- [Quota Reports](https://github.com/nanako0129/tokenbar/blob/main/Sources/TokenBarCore/QuotaResolver.swift): `Sources/TokenBarCore/QuotaResolver.swift`

### Dashboard and Settings

- [Dashboard Model](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/DashboardModel.swift): `Sources/Syrtis/DashboardModel.swift`
- [Dashboard Panel](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/PopoverView.swift): `Sources/Syrtis/PopoverView.swift`
- [Report Views](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/Views/ViewSwitch.swift): `Sources/Syrtis/Views/ViewSwitch.swift`
- [Usage Charts](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/Views/UsageChartCard.swift): `Sources/Syrtis/Views/UsageChartCard.swift`
- [3D Activity Graph](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/Charts/ContributionGraph3D.swift): `Sources/Syrtis/Charts/ContributionGraph3D.swift`
- [Settings Window](https://github.com/nanako0129/tokenbar/blob/main/Sources/Syrtis/SettingsWindowController.swift): `Sources/Syrtis/SettingsWindowController.swift`

### External Services

- **Tool Session Logs**
- **Quota Providers**
- **macOS Keychain**
- **Sparkle Service**

### Other components

- **User**

## Connections

- User → Status Item: opens dashboard
- Status Item → App Startup: activates app
- App Startup → Usage Data Source: starts refresh
- Usage Data Source → Tool Session Logs: reads logs
- Usage Data Source → Rust FFI Core: requests parsing
- Rust FFI Core → Usage Reports: returns data
- Rust FFI Core → Quota Providers: fetches quotas
- Rust FFI Core → macOS Keychain: reads credentials
- Usage Reports → Dashboard Model: supplies reports
- Quota Reports → Dashboard Model: supplies quota data
- Dashboard Model → Dashboard Panel: provides state
- Dashboard Panel → Report Views: selects lens
- Report Views → Usage Charts: renders usage
- Usage Charts → 3D Activity Graph: renders activity
- Dashboard Panel → Settings Window: opens settings
- Dashboard Model → Quota Menu Items: updates indicators
- User → App Updates: requests update
- App Updates → Sparkle Service: checks releases