# robinebers/openusage architecture

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

- Interactive diagram: https://gitdiagram.com/robinebers/openusage
- Repository: https://github.com/robinebers/openusage

## Overview

OpenUsage is a native macOS menu-bar dashboard for AI coding-plan usage. Its central workflow is to load local provider credentials, fetch or scan usage, normalize results into provider snapshots, and present cached data in the dashboard and menu-bar pins. The same runtime supports a one-shot CLI and loopback HTTP API. The README also documents customization, spend estimates from local logs and refreshed pricing, settings, proxy support, iCloud sync, and notifications. Provider and UI internals are represented at subsystem level where source excerpts were not sampled.

Main entry points: [`Sources/OpenUsage/Services/UsageReader.swift`](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Services/UsageReader.swift) (Usage reader), [`Sources/OpenUsage/App/StatusItemController.swift`](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/App/StatusItemController.swift) (Status item panel), [`Sources/OpenUsage/Views/DashboardView.swift`](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Views/DashboardView.swift) (Dashboard popover), [`Sources/OpenUsage/Providers/ProviderRuntime.swift`](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Providers/ProviderRuntime.swift) (Provider runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_status["Status item panel"]
  node_appcontainer["App container<br/>[AppContainer.swift]"]
end

subgraph group_providers["Provider data"]
  node_runtime["Provider runtime"]
  node_catalog["Provider catalog"]
  node_providerfamilies["Provider integrations"]
  node_credentials["Provider credentials"]
  node_usageclient["Usage clients"]
  node_snapshot["Provider snapshots"]
end

subgraph group_presentation["Dashboard"]
  node_dashboard["Dashboard popover"]
  node_widgets[("Widget data")]
  node_layout[("Layout customization<br/>[LayoutStore.swift]")]
  node_menubar["Menu bar pins"]
  node_settings["Settings screens"]
end

subgraph group_services["Shared services"]
  node_reader["Usage reader<br/>[UsageReader.swift]"]
  node_cache[("Snapshot cache")]
  node_spend["Spend aggregation"]
  node_pricing["Model pricing"]
  node_sync[("iCloud sync")]
end

subgraph group_interfaces["Read interfaces"]
  node_cli["One-shot CLI<br/>[OpenUsageCLI.swift]"]
  node_httpapi["Local HTTP API"]
end

node_user(("Mac user"))
node_usagefiles["Local usage logs"]
node_externalapps(("Other local apps"))

node_user -->|"opens panel"| node_status
node_status -->|"uses services"| node_appcontainer
node_status -->|"hosts view"| node_dashboard
node_appcontainer -->|"assembles"| node_catalog
node_catalog -->|"selects provider"| node_runtime
node_runtime -->|"loads auth"| node_credentials
node_runtime -->|"requests usage"| node_usageclient
node_usageclient -->|"integrates providers"| node_providerfamilies
node_providerfamilies -->|"maps usage"| node_snapshot
node_providerfamilies -.->|"scans logs"| node_usagefiles
node_reader -->|"refreshes providers"| node_runtime
node_reader -->|"updates cache"| node_cache
node_cache -->|"stores snapshots"| node_snapshot
node_dashboard -->|"reads usage"| node_reader
node_dashboard -->|"renders widgets"| node_widgets
node_dashboard -->|"reads layout"| node_layout
node_status -->|"shows pins"| node_menubar
node_spend -->|"estimates cost"| node_pricing
node_spend -.->|"aggregates logs"| node_usagefiles
node_cli -->|"reads cached limits"| node_reader
node_httpapi -->|"serves usage"| node_reader
node_externalapps -->|"requests limits"| node_httpapi
node_user -->|"configures app"| node_settings
node_settings -->|"configures sync"| node_sync

click node_status "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/App/StatusItemController.swift"
click node_appcontainer "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/App/AppContainer.swift"
click node_runtime "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Providers/ProviderRuntime.swift"
click node_catalog "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Providers/ProviderCatalog.swift"
click node_providerfamilies "https://github.com/robinebers/openusage/tree/main/Sources/OpenUsage/Providers"
click node_credentials "https://github.com/robinebers/openusage/tree/main/Sources/OpenUsage/Providers"
click node_usageclient "https://github.com/robinebers/openusage/tree/main/Sources/OpenUsage/Providers"
click node_snapshot "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Models/ProviderSnapshot.swift"
click node_reader "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Services/UsageReader.swift"
click node_cache "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Stores/ProviderSnapshotCache.swift"
click node_dashboard "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Views/DashboardView.swift"
click node_widgets "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Stores/WidgetDataStore.swift"
click node_layout "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Stores/LayoutStore.swift"
click node_menubar "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Models/MenuBarContent.swift"
click node_spend "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Services/UsageHistoryAggregator.swift"
click node_pricing "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Pricing/PricingCatalog.swift"
click node_sync "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Stores/ICloudUsageSyncStore.swift"
click node_cli "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsageCLI/OpenUsageCLI.swift"
click node_httpapi "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Services/LocalUsageServer.swift"
click node_settings "https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Views/SettingsScreen.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_appcontainer,node_user toneBlue
class node_runtime,node_catalog,node_providerfamilies,node_credentials,node_usageclient,node_snapshot toneAmber
class node_dashboard,node_widgets,node_layout,node_menubar,node_settings toneMint
class node_reader,node_cache,node_spend,node_pricing,node_sync toneRose
class node_cli,node_httpapi,node_usagefiles,node_externalapps toneIndigo
```

## Components

### App shell

- [Status item panel](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/App/StatusItemController.swift): `Sources/OpenUsage/App/StatusItemController.swift`
- [App container](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/App/AppContainer.swift): `Sources/OpenUsage/App/AppContainer.swift`

### Provider data

- [Provider runtime](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Providers/ProviderRuntime.swift): `Sources/OpenUsage/Providers/ProviderRuntime.swift`
- [Provider catalog](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Providers/ProviderCatalog.swift): `Sources/OpenUsage/Providers/ProviderCatalog.swift`
- [Provider integrations](https://github.com/robinebers/openusage/tree/main/Sources/OpenUsage/Providers): `Sources/OpenUsage/Providers`
- [Provider credentials](https://github.com/robinebers/openusage/tree/main/Sources/OpenUsage/Providers): `Sources/OpenUsage/Providers`
- [Usage clients](https://github.com/robinebers/openusage/tree/main/Sources/OpenUsage/Providers): `Sources/OpenUsage/Providers`
- [Provider snapshots](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Models/ProviderSnapshot.swift): `Sources/OpenUsage/Models/ProviderSnapshot.swift`

### Dashboard

- [Dashboard popover](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Views/DashboardView.swift): `Sources/OpenUsage/Views/DashboardView.swift`
- [Widget data](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Stores/WidgetDataStore.swift): `Sources/OpenUsage/Stores/WidgetDataStore.swift`
- [Layout customization](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Stores/LayoutStore.swift): `Sources/OpenUsage/Stores/LayoutStore.swift`
- [Menu bar pins](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Models/MenuBarContent.swift): `Sources/OpenUsage/Models/MenuBarContent.swift`
- [Settings screens](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Views/SettingsScreen.swift): `Sources/OpenUsage/Views/SettingsScreen.swift`

### Shared services

- [Usage reader](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Services/UsageReader.swift): `Sources/OpenUsage/Services/UsageReader.swift`
- [Snapshot cache](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Stores/ProviderSnapshotCache.swift): `Sources/OpenUsage/Stores/ProviderSnapshotCache.swift`
- [Spend aggregation](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Services/UsageHistoryAggregator.swift): `Sources/OpenUsage/Services/UsageHistoryAggregator.swift`
- [Model pricing](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Pricing/PricingCatalog.swift): `Sources/OpenUsage/Pricing/PricingCatalog.swift`
- [iCloud sync](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Stores/ICloudUsageSyncStore.swift): `Sources/OpenUsage/Stores/ICloudUsageSyncStore.swift`

### Read interfaces

- [One-shot CLI](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsageCLI/OpenUsageCLI.swift): `Sources/OpenUsageCLI/OpenUsageCLI.swift`
- [Local HTTP API](https://github.com/robinebers/openusage/blob/main/Sources/OpenUsage/Services/LocalUsageServer.swift): `Sources/OpenUsage/Services/LocalUsageServer.swift`

### Other components

- **Mac user**
- **Local usage logs**
- **Other local apps**

## Connections

- Mac user → Status item panel: opens panel
- Status item panel → App container: uses services
- Status item panel → Dashboard popover: hosts view
- App container → Provider catalog: assembles
- Provider catalog → Provider runtime: selects provider
- Provider runtime → Provider credentials: loads auth
- Provider runtime → Usage clients: requests usage
- Usage clients → Provider integrations: integrates providers
- Provider integrations → Provider snapshots: maps usage
- Provider integrations → Local usage logs: scans logs
- Usage reader → Provider runtime: refreshes providers
- Usage reader → Snapshot cache: updates cache
- Snapshot cache → Provider snapshots: stores snapshots
- Dashboard popover → Usage reader: reads usage
- Dashboard popover → Widget data: renders widgets
- Dashboard popover → Layout customization: reads layout
- Status item panel → Menu bar pins: shows pins
- Spend aggregation → Model pricing: estimates cost
- Spend aggregation → Local usage logs: aggregates logs
- One-shot CLI → Usage reader: reads cached limits
- Local HTTP API → Usage reader: serves usage
- Other local apps → Local HTTP API: requests limits
- Mac user → Settings screens: configures app
- Settings screens → iCloud sync: configures sync