# ithtelab/workbuddy-manager architecture

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

## Overview

WorkBuddy Manager is a web console and OpenAI-compatible gateway for operating workbuddy2api account pools. The main workflow is: an administrator enrolls and monitors accounts, configures keys and policies, then downstream clients send compatible requests through the gateway; the manager routes them to the selected upstream and records usage for logs and statistics. The README documents additional task automation, model discovery, settings, and update capabilities. Sampled source confirms the application entry point, authentication, account/upstream behavior, and UI state; several subsystem connections below follow documented responsibilities rather than inspected route implementations.

Main entry points: [`server/services/wb2api.py`](https://github.com/ithtelab/workbuddy-manager/blob/main/server/services/wb2api.py) (Upstream adapter), [`web/app/(main)/layout.tsx`](https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/layout.tsx) (Management UI), [`server/db.py`](https://github.com/ithtelab/workbuddy-manager/blob/main/server/db.py) (Manager database), [`web/app/(main)/tasks/page.tsx`](https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/tasks/page.tsx) (Tasks and logs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Management console"]
  node_console_ui["Management UI<br/>[layout.tsx]"]
  node_login_ui["Login page<br/>[page.tsx]"]
  node_accounts_ui["Accounts<br/>[page.tsx]"]
  node_keys_ui["Keys<br/>[page.tsx]"]
  node_ops_ui["Tasks and logs<br/>[page.tsx]"]
  node_settings_ui["Settings<br/>[layout.tsx]"]
  node_stats_ui["Dashboard and stats<br/>[page.tsx]"]
end

subgraph group_operations["Account operations"]
  node_account_api["Account API<br/>[accounts.py]"]
  node_task_services["Task services<br/>[taskrun.py]"]
  node_upstream_adapter["Upstream adapter<br/>[wb2api.py]"]
end

subgraph group_gateway["Gateway and policy"]
  node_gateway_api["Compatibility gateway<br/>[gateway.py]"]
  node_response_api["Responses API<br/>[responses.py]"]
  node_anthropic_api["Anthropic API<br/>[anthropic.py]"]
  node_key_api["Key management<br/>[keys.py]"]
end

subgraph group_platform["Services and state"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_security["Security services<br/>[security.py]"]
  node_logs_api["Logs and statistics<br/>[logs.py]"]
  node_stats_api["Statistics API<br/>[stats.py]"]
  node_settings_api["Settings and upstreams<br/>[settings.py]"]
  node_model_api["Model catalog API<br/>[models.py]"]
  node_update_service["Update service<br/>[updater.py]"]
  node_database[("Manager database<br/>[db.py]")]
end

node_admin(("Administrator"))
node_client(("API client"))
node_upstream["workbuddy2api"]

node_admin -->|"signs in"| node_login_ui
node_admin -->|"manages"| node_console_ui
node_client -->|"sends requests"| node_gateway_api
node_console_ui -->|"navigates"| node_accounts_ui
node_console_ui -->|"navigates"| node_keys_ui
node_console_ui -->|"navigates"| node_ops_ui
node_console_ui -->|"navigates"| node_settings_ui
node_console_ui -->|"navigates"| node_stats_ui
node_login_ui -->|"authenticates"| node_auth_api
node_accounts_ui -->|"manages accounts"| node_account_api
node_keys_ui -->|"manages keys"| node_key_api
node_ops_ui -->|"fetches records"| node_logs_api
node_ops_ui -->|"views tasks"| node_task_services
node_settings_ui -->|"reads and saves"| node_settings_api
node_stats_ui -->|"fetches usage"| node_stats_api
node_auth_api -->|"checks sessions"| node_security
node_account_api -->|"manages pool"| node_upstream_adapter
node_account_api -->|"stores account data"| node_database
node_task_services -->|"records results"| node_database
node_task_services -->|"runs account tasks"| node_upstream_adapter
node_gateway_api -->|"validates keys"| node_key_api
node_gateway_api -->|"forwards requests"| node_upstream_adapter
node_response_api -->|"forwards requests"| node_upstream_adapter
node_anthropic_api -->|"forwards requests"| node_upstream_adapter
node_key_api -->|"stores key records"| node_database
node_logs_api -->|"reads audit records"| node_database
node_stats_api -->|"reads usage data"| node_database
node_settings_api -->|"stores settings"| node_database
node_settings_api -->|"probes upstream"| node_upstream_adapter
node_model_api -->|"loads models"| node_upstream_adapter
node_upstream_adapter -->|"calls upstream"| node_upstream
node_upstream -->|"returns status"| node_upstream_adapter
node_update_service -->|"preserves manager data"| node_database

click node_console_ui "https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/layout.tsx"
click node_login_ui "https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(auth)/login/page.tsx"
click node_accounts_ui "https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/accounts/page.tsx"
click node_keys_ui "https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/keys/page.tsx"
click node_ops_ui "https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/tasks/page.tsx"
click node_settings_ui "https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/settings/layout.tsx"
click node_stats_ui "https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/stats/page.tsx"
click node_auth_api "https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/auth.py"
click node_account_api "https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/accounts.py"
click node_task_services "https://github.com/ithtelab/workbuddy-manager/blob/main/server/services/taskrun.py"
click node_upstream_adapter "https://github.com/ithtelab/workbuddy-manager/blob/main/server/services/wb2api.py"
click node_gateway_api "https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/gateway.py"
click node_response_api "https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/responses.py"
click node_anthropic_api "https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/anthropic.py"
click node_key_api "https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/keys.py"
click node_security "https://github.com/ithtelab/workbuddy-manager/blob/main/server/security.py"
click node_logs_api "https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/logs.py"
click node_stats_api "https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/stats.py"
click node_settings_api "https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/settings.py"
click node_model_api "https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/models.py"
click node_update_service "https://github.com/ithtelab/workbuddy-manager/blob/main/server/services/updater.py"
click node_database "https://github.com/ithtelab/workbuddy-manager/blob/main/server/db.py"

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_console_ui,node_login_ui,node_accounts_ui,node_keys_ui,node_ops_ui,node_settings_ui,node_stats_ui,node_client toneBlue
class node_account_api,node_task_services,node_upstream_adapter toneAmber
class node_gateway_api,node_response_api,node_anthropic_api,node_key_api,node_upstream toneMint
class node_auth_api,node_security,node_logs_api,node_stats_api,node_settings_api,node_model_api,node_update_service,node_database toneRose
class node_admin toneIndigo
```

## Components

### Management console

- [Management UI](https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/layout.tsx): `web/app/(main)/layout.tsx`
- [Login page](https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(auth)/login/page.tsx): `web/app/(auth)/login/page.tsx`
- [Accounts](https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/accounts/page.tsx): `web/app/(main)/accounts/page.tsx`
- [Keys](https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/keys/page.tsx): `web/app/(main)/keys/page.tsx`
- [Tasks and logs](https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/tasks/page.tsx): `web/app/(main)/tasks/page.tsx`
- [Settings](https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/settings/layout.tsx): `web/app/(main)/settings/layout.tsx`
- [Dashboard and stats](https://github.com/ithtelab/workbuddy-manager/blob/main/web/app/(main)/stats/page.tsx): `web/app/(main)/stats/page.tsx`

### Account operations

- [Account API](https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/accounts.py): `server/routers/accounts.py`
- [Task services](https://github.com/ithtelab/workbuddy-manager/blob/main/server/services/taskrun.py): `server/services/taskrun.py`
- [Upstream adapter](https://github.com/ithtelab/workbuddy-manager/blob/main/server/services/wb2api.py): `server/services/wb2api.py`

### Gateway and policy

- [Compatibility gateway](https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/gateway.py): `server/routers/gateway.py`
- [Responses API](https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/responses.py): `server/routers/responses.py`
- [Anthropic API](https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/anthropic.py): `server/routers/anthropic.py`
- [Key management](https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/keys.py): `server/routers/keys.py`

### Services and state

- [Authentication API](https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/auth.py): `server/routers/auth.py`
- [Security services](https://github.com/ithtelab/workbuddy-manager/blob/main/server/security.py): `server/security.py`
- [Logs and statistics](https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/logs.py): `server/routers/logs.py`
- [Statistics API](https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/stats.py): `server/routers/stats.py`
- [Settings and upstreams](https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/settings.py): `server/routers/settings.py`
- [Model catalog API](https://github.com/ithtelab/workbuddy-manager/blob/main/server/routers/models.py): `server/routers/models.py`
- [Update service](https://github.com/ithtelab/workbuddy-manager/blob/main/server/services/updater.py): `server/services/updater.py`
- [Manager database](https://github.com/ithtelab/workbuddy-manager/blob/main/server/db.py): `server/db.py`

### Other components

- **Administrator**
- **API client**
- **workbuddy2api**

## Connections

- Administrator → Login page: signs in
- Administrator → Management UI: manages
- API client → Compatibility gateway: sends requests
- Management UI → Accounts: navigates
- Management UI → Keys: navigates
- Management UI → Tasks and logs: navigates
- Management UI → Settings: navigates
- Management UI → Dashboard and stats: navigates
- Login page → Authentication API: authenticates
- Accounts → Account API: manages accounts
- Keys → Key management: manages keys
- Tasks and logs → Logs and statistics: fetches records
- Tasks and logs → Task services: views tasks
- Settings → Settings and upstreams: reads and saves
- Dashboard and stats → Statistics API: fetches usage
- Authentication API → Security services: checks sessions
- Account API → Upstream adapter: manages pool
- Account API → Manager database: stores account data
- Task services → Manager database: records results
- Task services → Upstream adapter: runs account tasks
- Compatibility gateway → Key management: validates keys
- Compatibility gateway → Upstream adapter: forwards requests
- Responses API → Upstream adapter: forwards requests
- Anthropic API → Upstream adapter: forwards requests
- Key management → Manager database: stores key records
- Logs and statistics → Manager database: reads audit records
- Statistics API → Manager database: reads usage data
- Settings and upstreams → Manager database: stores settings
- Settings and upstreams → Upstream adapter: probes upstream
- Model catalog API → Upstream adapter: loads models
- Upstream adapter → workbuddy2api: calls upstream
- workbuddy2api → Upstream adapter: returns status
- Update service → Manager database: preserves manager data