# changexbc/workbuddy-switch architecture

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

## Overview

WorkBuddy Switch is a desktop and local-web account manager for WorkBuddy and CodeBuddy clients. The main workflow is to add or import accounts, inspect account/credit status, then switch a selected client’s credentials, optionally copying or synchronizing sessions. Separate workflows provide usage statistics, automatic CLI account rotation, and updates; the desktop app also hosts the Agent Companion session rail. The README documents these capabilities, while sampled source confirms the frontend/API boundary, background rotation, session-copy behavior, and desktop update service; unsampled subsystem wiring is shown only where documented.

Main entry points: [`crates/wb-switch-core/src/lib.rs`](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/lib.rs) (Core modules), [`src/lib/api.ts`](https://github.com/changexbc/workbuddy-switch/blob/main/src/lib/api.ts) (Frontend API), [`src/App.tsx`](https://github.com/changexbc/workbuddy-switch/blob/main/src/App.tsx) (App shell), [`crates/wb-switch-core/src/modules/switch.rs`](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/switch.rs) (Client switching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_frontend["App shell<br/>[App.tsx]"]
  node_accounts_ui["Account management<br/>[AccountsPage.tsx]"]
  node_credit_ui["Credit statistics"]
  node_token_ui["Token statistics<br/>[TokenStatsPage.tsx]"]
  node_settings_ui["Settings<br/>[SettingsPage.tsx]"]
end

subgraph group_runtime["Application runtime"]
  node_api_client["Frontend API<br/>[api.ts]"]
  node_desktop_commands["Tauri commands<br/>[commands.rs]"]
  node_web_server["Local web server<br/>[api.rs]"]
  node_core["Core modules<br/>[lib.rs]"]
end

subgraph group_accounts["Accounts and clients"]
  node_account_store[("Account and auth<br/>[account.rs]")]
  node_oauth["OAuth login<br/>[oauth.rs]"]
  node_account_exchange["Import and export<br/>[export_import.rs]"]
  node_client_switch["Client switching<br/>[switch.rs]"]
  node_session_copy["Session copy<br/>[session.rs]"]
  node_session_sync[("Session linking<br/>[session_link.rs]")]
  node_client_integrations["Client integrations"]
end

subgraph group_insights["Usage and automation"]
  node_credits["Credit expiry<br/>[credits.rs]"]
  node_credit_usage["Credit usage stats<br/>[credit_usage.rs]"]
  node_token_stats["Token statistics<br/>[token_stats.rs]"]
  node_rotation["Automatic rotation<br/>[rotate.rs]"]
end

subgraph group_desktop["Desktop services"]
  node_companion["Agent Companion<br/>[companion.rs]"]
  node_tray["Tray controls<br/>[tray.rs]"]
  node_updates["Update service<br/>[update_service.rs]"]
end

node_user(("User"))
node_release_service(("GitHub Releases"))
node_client_apps(("Supported client apps"))

node_user -->|"uses"| node_frontend
node_frontend -->|"routes to"| node_accounts_ui
node_frontend -->|"routes to"| node_credit_ui
node_frontend -->|"routes to"| node_token_ui
node_frontend -->|"routes to"| node_settings_ui
node_accounts_ui -->|"requests"| node_api_client
node_credit_ui -->|"requests"| node_api_client
node_token_ui -->|"requests"| node_api_client
node_settings_ui -->|"requests"| node_api_client
node_api_client -->|"invokes"| node_desktop_commands
node_api_client -.->|"requests"| node_web_server
node_desktop_commands -->|"dispatches"| node_core
node_web_server -->|"dispatches"| node_core
node_core -->|"provides login"| node_oauth
node_core -->|"provides backup"| node_account_exchange
node_core -->|"reads/writes"| node_account_store
node_core -->|"dispatches switch"| node_client_switch
node_client_switch -->|"reads credentials"| node_account_store
node_client_switch -->|"updates clients"| node_client_integrations
node_client_integrations -->|"writes credentials"| node_client_apps
node_client_switch -->|"copies sessions"| node_session_copy
node_session_copy -->|"registers links"| node_session_sync
node_session_sync -->|"stores metadata"| node_account_store
node_core -->|"queries expiry"| node_credits
node_core -->|"loads usage"| node_credit_usage
node_core -->|"loads statistics"| node_token_stats
node_core -->|"runs rotation"| node_rotation
node_rotation -->|"selects account"| node_account_store
node_rotation -->|"sets CLI default"| node_client_integrations
node_desktop_commands -->|"controls companion"| node_companion
node_tray -->|"toggles visibility"| node_companion
node_settings_ui -->|"requests update"| node_updates
node_updates -->|"checks releases"| node_release_service
node_updates -->|"refreshes menu"| node_tray

click node_frontend "https://github.com/changexbc/workbuddy-switch/blob/main/src/App.tsx"
click node_accounts_ui "https://github.com/changexbc/workbuddy-switch/blob/main/src/pages/AccountsPage.tsx"
click node_credit_ui "https://github.com/changexbc/workbuddy-switch/blob/main/src/pages/CreditStatsPage.tsx"
click node_token_ui "https://github.com/changexbc/workbuddy-switch/blob/main/src/pages/TokenStatsPage.tsx"
click node_settings_ui "https://github.com/changexbc/workbuddy-switch/blob/main/src/pages/SettingsPage.tsx"
click node_api_client "https://github.com/changexbc/workbuddy-switch/blob/main/src/lib/api.ts"
click node_desktop_commands "https://github.com/changexbc/workbuddy-switch/blob/main/src-tauri/src/commands.rs"
click node_web_server "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-server/src/api.rs"
click node_core "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/lib.rs"
click node_account_store "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/account.rs"
click node_oauth "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/oauth.rs"
click node_account_exchange "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/export_import.rs"
click node_client_switch "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/switch.rs"
click node_session_copy "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/session.rs"
click node_session_sync "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/session_link.rs"
click node_client_integrations "https://github.com/changexbc/workbuddy-switch/tree/main/crates/wb-switch-core/src/modules"
click node_credits "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/credits.rs"
click node_credit_usage "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/credit_usage.rs"
click node_token_stats "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/token_stats.rs"
click node_rotation "https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/rotate.rs"
click node_companion "https://github.com/changexbc/workbuddy-switch/blob/main/src-tauri/src/companion.rs"
click node_tray "https://github.com/changexbc/workbuddy-switch/blob/main/src-tauri/src/tray.rs"
click node_updates "https://github.com/changexbc/workbuddy-switch/blob/main/src-tauri/src/update_service.rs"

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_frontend,node_accounts_ui,node_credit_ui,node_token_ui,node_settings_ui,node_user,node_client_apps toneBlue
class node_api_client,node_desktop_commands,node_web_server,node_core toneAmber
class node_account_store,node_oauth,node_account_exchange,node_client_switch,node_session_copy,node_session_sync,node_client_integrations toneMint
class node_credits,node_credit_usage,node_token_stats,node_rotation toneRose
class node_companion,node_tray,node_updates,node_release_service toneIndigo
```

## Components

### User interface

- [App shell](https://github.com/changexbc/workbuddy-switch/blob/main/src/App.tsx): `src/App.tsx`
- [Account management](https://github.com/changexbc/workbuddy-switch/blob/main/src/pages/AccountsPage.tsx): `src/pages/AccountsPage.tsx`
- [Credit statistics](https://github.com/changexbc/workbuddy-switch/blob/main/src/pages/CreditStatsPage.tsx): `src/pages/CreditStatsPage.tsx`
- [Token statistics](https://github.com/changexbc/workbuddy-switch/blob/main/src/pages/TokenStatsPage.tsx): `src/pages/TokenStatsPage.tsx`
- [Settings](https://github.com/changexbc/workbuddy-switch/blob/main/src/pages/SettingsPage.tsx): `src/pages/SettingsPage.tsx`

### Application runtime

- [Frontend API](https://github.com/changexbc/workbuddy-switch/blob/main/src/lib/api.ts): `src/lib/api.ts`
- [Tauri commands](https://github.com/changexbc/workbuddy-switch/blob/main/src-tauri/src/commands.rs): `src-tauri/src/commands.rs`
- [Local web server](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-server/src/api.rs): `crates/wb-switch-server/src/api.rs`
- [Core modules](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/lib.rs): `crates/wb-switch-core/src/lib.rs`

### Accounts and clients

- [Account and auth](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/account.rs): `crates/wb-switch-core/src/modules/account.rs`
- [OAuth login](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/oauth.rs): `crates/wb-switch-core/src/modules/oauth.rs`
- [Import and export](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/export_import.rs): `crates/wb-switch-core/src/modules/export_import.rs`
- [Client switching](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/switch.rs): `crates/wb-switch-core/src/modules/switch.rs`
- [Session copy](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/session.rs): `crates/wb-switch-core/src/modules/session.rs`
- [Session linking](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/session_link.rs): `crates/wb-switch-core/src/modules/session_link.rs`
- [Client integrations](https://github.com/changexbc/workbuddy-switch/tree/main/crates/wb-switch-core/src/modules): `crates/wb-switch-core/src/modules`

### Usage and automation

- [Credit expiry](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/credits.rs): `crates/wb-switch-core/src/modules/credits.rs`
- [Credit usage stats](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/credit_usage.rs): `crates/wb-switch-core/src/modules/credit_usage.rs`
- [Token statistics](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/token_stats.rs): `crates/wb-switch-core/src/modules/token_stats.rs`
- [Automatic rotation](https://github.com/changexbc/workbuddy-switch/blob/main/crates/wb-switch-core/src/modules/rotate.rs): `crates/wb-switch-core/src/modules/rotate.rs`

### Desktop services

- [Agent Companion](https://github.com/changexbc/workbuddy-switch/blob/main/src-tauri/src/companion.rs): `src-tauri/src/companion.rs`
- [Tray controls](https://github.com/changexbc/workbuddy-switch/blob/main/src-tauri/src/tray.rs): `src-tauri/src/tray.rs`
- [Update service](https://github.com/changexbc/workbuddy-switch/blob/main/src-tauri/src/update_service.rs): `src-tauri/src/update_service.rs`

### Other components

- **User**
- **GitHub Releases**
- **Supported client apps**

## Connections

- User → App shell: uses
- App shell → Account management: routes to
- App shell → Credit statistics: routes to
- App shell → Token statistics: routes to
- App shell → Settings: routes to
- Account management → Frontend API: requests
- Credit statistics → Frontend API: requests
- Token statistics → Frontend API: requests
- Settings → Frontend API: requests
- Frontend API → Tauri commands: invokes
- Frontend API → Local web server: requests
- Tauri commands → Core modules: dispatches
- Local web server → Core modules: dispatches
- Core modules → OAuth login: provides login
- Core modules → Import and export: provides backup
- Core modules → Account and auth: reads/writes
- Core modules → Client switching: dispatches switch
- Client switching → Account and auth: reads credentials
- Client switching → Client integrations: updates clients
- Client integrations → Supported client apps: writes credentials
- Client switching → Session copy: copies sessions
- Session copy → Session linking: registers links
- Session linking → Account and auth: stores metadata
- Core modules → Credit expiry: queries expiry
- Core modules → Credit usage stats: loads usage
- Core modules → Token statistics: loads statistics
- Core modules → Automatic rotation: runs rotation
- Automatic rotation → Account and auth: selects account
- Automatic rotation → Client integrations: sets CLI default
- Tauri commands → Agent Companion: controls companion
- Tray controls → Agent Companion: toggles visibility
- Settings → Update service: requests update
- Update service → GitHub Releases: checks releases
- Update service → Tray controls: refreshes menu