# chattymin/poketokenbar architecture

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

- Interactive diagram: https://gitdiagram.com/chattymin/poketokenbar
- Repository: https://github.com/chattymin/poketokenbar

## Overview

PokeTokenBar is a macOS menu-bar usage tracker wrapped in a Pokémon companion game. The main workflow is local coding-tool logs and official quota sources → usage aggregation → companion growth, rewards, and collection → menu-bar, popover, or desktop-pet presentation. The graph also preserves the documented shop, bag, settings, and Pokémon-data capabilities. Source excerpts and the index support the central wiring; some feature-level connections are documented by the README rather than inspected implementation.

Main entry points: [`Sources/PokeTokenBar/Core/UsageStore.swift`](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/UsageStore.swift) (Usage state), [`Sources/PokeTokenBar/Core/CompanionStore.swift`](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/CompanionStore.swift) (Companion state), [`Sources/PokeTokenBar/UI/PopoverView.swift`](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/PopoverView.swift) (Usage popover), [`Sources/PokeTokenBar/PokeTokenBarApp.swift`](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/PokeTokenBarApp.swift) (App lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and presentation"]
  node_app["App lifecycle"]
  node_popover["Usage popover<br/>[PopoverView.swift]"]
  node_settings["Settings<br/>[SettingsView.swift]"]
  node_pet["Desktop pet"]
  node_companion_view["Companion display"]
  node_shop["Token shop<br/>[ShopView.swift]"]
  node_bag["Item bag<br/>[BagView.swift]"]
  node_recap["Usage recap"]
end

subgraph group_usage["Usage tracking"]
  node_usage_store["Usage state<br/>[UsageStore.swift]"]
  node_local_reader["Local log reader"]
  node_additional_reader["Additional readers"]
  node_scan_roots["Scan roots"]
  node_oauth_limits["OAuth limits"]
  node_session_limits["Session-key limits"]
  node_other_limits["Provider limits"]
end

subgraph group_game["Companion game"]
  node_companion_store["Companion state"]
  node_companion_model["Game model"]
  node_poke_api["Pokémon data"]
end

subgraph group_services["Shared services"]
  node_save_transfer["Save transfer<br/>[SaveTransfer.swift]"]
  node_localization["Localization<br/>[Localization.swift]"]
end

node_user(("Mac user"))
node_local_data[("Coding-tool data")]
node_external_api(("PokéAPI"))

node_user -->|"opens"| node_app
node_app -->|"creates"| node_usage_store
node_app -->|"creates"| node_companion_store
node_app -->|"presents"| node_popover
node_app -->|"offers"| node_pet
node_user -->|"generates usage"| node_local_data
node_local_data -->|"reads logs"| node_local_reader
node_local_reader -->|"uses roots"| node_scan_roots
node_local_data -->|"reads provider data"| node_additional_reader
node_usage_store -->|"refreshes"| node_local_reader
node_usage_store -->|"fetches usage"| node_additional_reader
node_usage_store -->|"fetches quotas"| node_oauth_limits
node_usage_store -->|"fetches quotas"| node_session_limits
node_usage_store -->|"fetches quotas"| node_other_limits
node_usage_store -.->|"drives growth"| node_companion_store
node_usage_store -->|"supplies totals"| node_popover
node_usage_store -->|"supplies history"| node_recap
node_usage_store -->|"supplies usage"| node_pet
node_companion_store -->|"persists state"| node_companion_model
node_companion_store -->|"requests species"| node_poke_api
node_poke_api -.->|"fetches data"| node_external_api
node_companion_store -->|"feeds display"| node_companion_view
node_companion_store -->|"handles purchases"| node_shop
node_companion_store -->|"handles items"| node_bag
node_companion_store -->|"exports snapshots"| node_save_transfer
node_user -->|"configures"| node_settings
node_settings -->|"changes tracking"| node_usage_store
node_popover -->|"shows tab"| node_shop
node_popover -->|"shows tab"| node_bag
node_popover -.->|"shows companion"| node_companion_view
node_localization -.->|"localizes labels"| node_popover

click node_app "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/PokeTokenBarApp.swift"
click node_popover "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/PopoverView.swift"
click node_settings "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/SettingsView.swift"
click node_pet "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/FloatingPetPanel.swift"
click node_usage_store "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/UsageStore.swift"
click node_local_reader "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/LocalUsageReader.swift"
click node_additional_reader "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/LocalAdditionalUsageProvider.swift"
click node_scan_roots "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/CustomScanRoots.swift"
click node_oauth_limits "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/OAuthLimitsProvider.swift"
click node_session_limits "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/SessionKeyLimitsProvider.swift"
click node_other_limits "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/CodexRateLimitsProvider.swift"
click node_companion_store "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/CompanionStore.swift"
click node_companion_model "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/CompanionModel.swift"
click node_poke_api "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/PokeAPIClient.swift"
click node_companion_view "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/CompanionView.swift"
click node_shop "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/ShopView.swift"
click node_bag "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/BagView.swift"
click node_recap "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/UsageRecapView.swift"
click node_save_transfer "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/SaveTransfer.swift"
click node_localization "https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/Localization.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_app,node_popover,node_settings,node_pet,node_companion_view,node_shop,node_bag,node_recap,node_user toneBlue
class node_usage_store,node_local_reader,node_additional_reader,node_scan_roots,node_oauth_limits,node_session_limits,node_other_limits,node_local_data toneAmber
class node_companion_store,node_companion_model,node_poke_api,node_external_api toneMint
class node_save_transfer,node_localization toneRose
```

## Components

### App and presentation

- [App lifecycle](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/PokeTokenBarApp.swift): `Sources/PokeTokenBar/PokeTokenBarApp.swift`
- [Usage popover](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/PopoverView.swift): `Sources/PokeTokenBar/UI/PopoverView.swift`
- [Settings](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/SettingsView.swift): `Sources/PokeTokenBar/UI/SettingsView.swift`
- [Desktop pet](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/FloatingPetPanel.swift): `Sources/PokeTokenBar/UI/FloatingPetPanel.swift`
- [Companion display](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/CompanionView.swift): `Sources/PokeTokenBar/UI/CompanionView.swift`
- [Token shop](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/ShopView.swift): `Sources/PokeTokenBar/UI/ShopView.swift`
- [Item bag](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/BagView.swift): `Sources/PokeTokenBar/UI/BagView.swift`
- [Usage recap](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/UI/UsageRecapView.swift): `Sources/PokeTokenBar/UI/UsageRecapView.swift`

### Usage tracking

- [Usage state](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/UsageStore.swift): `Sources/PokeTokenBar/Core/UsageStore.swift`
- [Local log reader](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/LocalUsageReader.swift): `Sources/PokeTokenBar/Core/LocalUsageReader.swift`
- [Additional readers](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/LocalAdditionalUsageProvider.swift): `Sources/PokeTokenBar/Core/LocalAdditionalUsageProvider.swift`
- [Scan roots](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/CustomScanRoots.swift): `Sources/PokeTokenBar/Core/CustomScanRoots.swift`
- [OAuth limits](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/OAuthLimitsProvider.swift): `Sources/PokeTokenBar/Core/OAuthLimitsProvider.swift`
- [Session-key limits](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/SessionKeyLimitsProvider.swift): `Sources/PokeTokenBar/Core/SessionKeyLimitsProvider.swift`
- [Provider limits](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/CodexRateLimitsProvider.swift): `Sources/PokeTokenBar/Core/CodexRateLimitsProvider.swift`

### Companion game

- [Companion state](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/CompanionStore.swift): `Sources/PokeTokenBar/Core/CompanionStore.swift`
- [Game model](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/CompanionModel.swift): `Sources/PokeTokenBar/Core/CompanionModel.swift`
- [Pokémon data](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/PokeAPIClient.swift): `Sources/PokeTokenBar/Core/PokeAPIClient.swift`

### Shared services

- [Save transfer](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/SaveTransfer.swift): `Sources/PokeTokenBar/Core/SaveTransfer.swift`
- [Localization](https://github.com/chattymin/poketokenbar/blob/main/Sources/PokeTokenBar/Core/Localization.swift): `Sources/PokeTokenBar/Core/Localization.swift`

### Other components

- **Mac user**
- **Coding-tool data**
- **PokéAPI**

## Connections

- Mac user → App lifecycle: opens (evidence: `README.md`)
- App lifecycle → Usage state: creates (evidence: `Sources/PokeTokenBar/PokeTokenBarApp.swift`)
- App lifecycle → Companion state: creates (evidence: `Sources/PokeTokenBar/PokeTokenBarApp.swift`)
- App lifecycle → Usage popover: presents (evidence: `Sources/PokeTokenBar/PokeTokenBarApp.swift`)
- App lifecycle → Desktop pet: offers (evidence: `README.md`)
- Mac user → Coding-tool data: generates usage (evidence: `README.md`)
- Coding-tool data → Local log reader: reads logs (evidence: `Sources/PokeTokenBar/Core/LocalUsageReader.swift`)
- Local log reader → Scan roots: uses roots (evidence: `Sources/PokeTokenBar/Core/LocalUsageReader.swift`)
- Coding-tool data → Additional readers: reads provider data (evidence: `Sources/PokeTokenBar/Core/LocalAdditionalUsageProvider.swift`)
- Usage state → Local log reader: refreshes (evidence: `Sources/PokeTokenBar/Core/UsageStore.swift`)
- Usage state → Additional readers: fetches usage (evidence: `Sources/PokeTokenBar/Core/UsageStore.swift`)
- Usage state → OAuth limits: fetches quotas (evidence: `Sources/PokeTokenBar/Core/UsageStore.swift`)
- Usage state → Session-key limits: fetches quotas (evidence: `Sources/PokeTokenBar/Core/UsageStore.swift`)
- Usage state → Provider limits: fetches quotas (evidence: `Sources/PokeTokenBar/Core/UsageStore.swift`)
- Usage state → Companion state: drives growth
- Usage state → Usage popover: supplies totals (evidence: `Sources/PokeTokenBar/UI/PopoverView.swift`)
- Usage state → Usage recap: supplies history (evidence: `Sources/PokeTokenBar/UI/UsageRecapView.swift`)
- Usage state → Desktop pet: supplies usage (evidence: `Sources/PokeTokenBar/UI/FloatingPetPanel.swift`)
- Companion state → Game model: persists state (evidence: `Sources/PokeTokenBar/Core/CompanionStore.swift`)
- Companion state → Pokémon data: requests species (evidence: `Sources/PokeTokenBar/Core/CompanionStore.swift`)
- Pokémon data → PokéAPI: fetches data
- Companion state → Companion display: feeds display (evidence: `Sources/PokeTokenBar/UI/CompanionView.swift`)
- Companion state → Token shop: handles purchases (evidence: `Sources/PokeTokenBar/UI/ShopView.swift`)
- Companion state → Item bag: handles items (evidence: `Sources/PokeTokenBar/UI/BagView.swift`)
- Companion state → Save transfer: exports snapshots (evidence: `Sources/PokeTokenBar/Core/CompanionStore.swift`)
- Mac user → Settings: configures (evidence: `README.md`)
- Settings → Usage state: changes tracking (evidence: `Sources/PokeTokenBar/UI/SettingsView.swift`)
- Usage popover → Token shop: shows tab (evidence: `Sources/PokeTokenBar/UI/PopoverView.swift`)
- Usage popover → Item bag: shows tab (evidence: `Sources/PokeTokenBar/UI/PopoverView.swift`)
- Usage popover → Companion display: shows companion
- Localization → Usage popover: localizes labels