# yetone/magpie architecture

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

- Interactive diagram: https://gitdiagram.com/yetone/magpie
- Repository: https://github.com/yetone/magpie

## Overview

Magpie is a local model gateway and cross-agent configuration app. The main workflow is: configure a provider, choose a model for an installed agent, then let that agent send requests through the local gateway, which translates and routes them to provider accounts. Routing groups provide failover; the product also includes agent configuration, usage/session views, plugins, and image, vision, and search tools. The graph combines README-documented behavior with relationships visible in the sampled source index; unsampled subsystem links are omitted where their callers are not shown.

Main entry points: [`internal/cli/main.go`](https://github.com/yetone/magpie/blob/main/internal/cli/main.go) (CLI commands), [`internal/gui/app.go`](https://github.com/yetone/magpie/blob/main/internal/gui/app.go) (Desktop app), [`internal/gateway/routing.go`](https://github.com/yetone/magpie/blob/main/internal/gateway/routing.go) (Request routing), [`internal/provider/routing.go`](https://github.com/yetone/magpie/blob/main/internal/provider/routing.go) (Provider accounts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[main.go]"]
  node_desktop["Desktop app<br/>[app.go]"]
  node_terminal_ui["Terminal UI<br/>[routing.go]"]
end

subgraph group_configuration["Agents and configuration"]
  node_agent_configs["Agent config adapters<br/>[preview.go]"]
  node_settings[("Preferences<br/>[settings.go]")]
  node_providers[("Provider accounts<br/>[routing.go]")]
  node_model_catalog["Model catalog<br/>[codexcat.go]"]
  node_profiles[("Profiles<br/>[profile.go]")]
end

subgraph group_gateway["Gateway and routing"]
  node_gateway_server["Local gateway<br/>[gateway.go]"]
  node_request_routing["Request routing<br/>[routing.go]"]
  node_upstream["Provider requests<br/>[upstream.go]"]
  node_plugins["Gateway plugins<br/>[pluginrt.go]"]
  node_mcp_auth["MCP sign-in relay<br/>[mcpauth.go]"]
end

subgraph group_capabilities["Tools and insights"]
  node_image_tools["Image and MCP tools<br/>[imagemcp.go]"]
  node_library["Skills library<br/>[skills.go]"]
  node_session_history[("Session history<br/>[sessions.go]")]
  node_usage_records[("Usage records")]
  node_data_sync["Backup and sync<br/>[davsync.go]"]
end

node_user(("User"))
node_agents_client(("Agent clients"))
node_model_services(("Model services"))

node_user -->|"runs commands"| node_cli
node_user -->|"uses app"| node_desktop
node_user -->|"opens TUI"| node_terminal_ui
node_agents_client -->|"sends requests"| node_gateway_server
node_gateway_server -->|"dispatches requests"| node_request_routing
node_request_routing -->|"selects accounts"| node_providers
node_request_routing -.->|"forwards requests"| node_upstream
node_upstream -->|"calls model API"| node_model_services
node_request_routing -.->|"supports plugins"| node_plugins
node_agents_client -.->|"uses models directly"| node_model_services
node_cli -->|"changes agent model"| node_agent_configs
node_cli -->|"loads preferences"| node_settings
node_cli -->|"manages profiles"| node_profiles
node_cli -->|"manages providers"| node_providers
node_cli -->|"reads catalog"| node_model_catalog
node_desktop -->|"loads preferences"| node_settings
node_desktop -->|"manages agents"| node_agent_configs
node_desktop -->|"opens library"| node_library
node_terminal_ui -->|"edits routing groups"| node_providers
node_model_catalog -->|"reads preferences"| node_settings
node_request_routing -->|"records usage"| node_usage_records
node_session_history -->|"uses provider data"| node_providers
node_image_tools -->|"uses gateway"| node_gateway_server
node_image_tools -->|"reads preferences"| node_settings
node_mcp_auth -->|"relays MCP requests"| node_gateway_server
node_desktop -.->|"shows sessions"| node_session_history
node_cli -->|"runs sync"| node_data_sync
node_data_sync -->|"backs up provider data"| node_providers
node_data_sync -->|"backs up library"| node_library

click node_cli "https://github.com/yetone/magpie/blob/main/internal/cli/main.go"
click node_desktop "https://github.com/yetone/magpie/blob/main/internal/gui/app.go"
click node_terminal_ui "https://github.com/yetone/magpie/blob/main/internal/tui/routing.go"
click node_agent_configs "https://github.com/yetone/magpie/blob/main/internal/agent/preview.go"
click node_settings "https://github.com/yetone/magpie/blob/main/internal/settings/settings.go"
click node_providers "https://github.com/yetone/magpie/blob/main/internal/provider/routing.go"
click node_model_catalog "https://github.com/yetone/magpie/blob/main/internal/codexcat/codexcat.go"
click node_profiles "https://github.com/yetone/magpie/blob/main/internal/profile/profile.go"
click node_gateway_server "https://github.com/yetone/magpie/blob/main/internal/gateway/gateway.go"
click node_request_routing "https://github.com/yetone/magpie/blob/main/internal/gateway/routing.go"
click node_upstream "https://github.com/yetone/magpie/blob/main/internal/upstream/upstream.go"
click node_plugins "https://github.com/yetone/magpie/blob/main/internal/pluginrt/pluginrt.go"
click node_mcp_auth "https://github.com/yetone/magpie/blob/main/internal/mcpauth/mcpauth.go"
click node_image_tools "https://github.com/yetone/magpie/blob/main/internal/imagemcp/imagemcp.go"
click node_library "https://github.com/yetone/magpie/blob/main/internal/library/skills.go"
click node_session_history "https://github.com/yetone/magpie/blob/main/internal/sessions/sessions.go"
click node_usage_records "https://github.com/yetone/magpie/blob/main/internal/usage/gateway_sessions.go"
click node_data_sync "https://github.com/yetone/magpie/blob/main/internal/davsync/davsync.go"

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_cli,node_desktop,node_terminal_ui,node_user,node_agents_client toneBlue
class node_agent_configs,node_settings,node_providers,node_model_catalog,node_profiles toneAmber
class node_gateway_server,node_request_routing,node_upstream,node_plugins,node_mcp_auth toneMint
class node_image_tools,node_library,node_session_history,node_usage_records,node_data_sync toneRose
class node_model_services toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/yetone/magpie/blob/main/internal/cli/main.go): `internal/cli/main.go`
- [Desktop app](https://github.com/yetone/magpie/blob/main/internal/gui/app.go): `internal/gui/app.go`
- [Terminal UI](https://github.com/yetone/magpie/blob/main/internal/tui/routing.go): `internal/tui/routing.go`

### Agents and configuration

- [Agent config adapters](https://github.com/yetone/magpie/blob/main/internal/agent/preview.go): `internal/agent/preview.go`
- [Preferences](https://github.com/yetone/magpie/blob/main/internal/settings/settings.go): `internal/settings/settings.go`
- [Provider accounts](https://github.com/yetone/magpie/blob/main/internal/provider/routing.go): `internal/provider/routing.go`
- [Model catalog](https://github.com/yetone/magpie/blob/main/internal/codexcat/codexcat.go): `internal/codexcat/codexcat.go`
- [Profiles](https://github.com/yetone/magpie/blob/main/internal/profile/profile.go): `internal/profile/profile.go`

### Gateway and routing

- [Local gateway](https://github.com/yetone/magpie/blob/main/internal/gateway/gateway.go): `internal/gateway/gateway.go`
- [Request routing](https://github.com/yetone/magpie/blob/main/internal/gateway/routing.go): `internal/gateway/routing.go`
- [Provider requests](https://github.com/yetone/magpie/blob/main/internal/upstream/upstream.go): `internal/upstream/upstream.go`
- [Gateway plugins](https://github.com/yetone/magpie/blob/main/internal/pluginrt/pluginrt.go): `internal/pluginrt/pluginrt.go`
- [MCP sign-in relay](https://github.com/yetone/magpie/blob/main/internal/mcpauth/mcpauth.go): `internal/mcpauth/mcpauth.go`

### Tools and insights

- [Image and MCP tools](https://github.com/yetone/magpie/blob/main/internal/imagemcp/imagemcp.go): `internal/imagemcp/imagemcp.go`
- [Skills library](https://github.com/yetone/magpie/blob/main/internal/library/skills.go): `internal/library/skills.go`
- [Session history](https://github.com/yetone/magpie/blob/main/internal/sessions/sessions.go): `internal/sessions/sessions.go`
- [Usage records](https://github.com/yetone/magpie/blob/main/internal/usage/gateway_sessions.go): `internal/usage/gateway_sessions.go`
- [Backup and sync](https://github.com/yetone/magpie/blob/main/internal/davsync/davsync.go): `internal/davsync/davsync.go`

### Other components

- **User**
- **Agent clients**
- **Model services**

## Connections

- User → CLI commands: runs commands (evidence: `README.md`)
- User → Desktop app: uses app (evidence: `README.md`)
- User → Terminal UI: opens TUI (evidence: `README.md`)
- Agent clients → Local gateway: sends requests (evidence: `README.md`)
- Local gateway → Request routing: dispatches requests (evidence: `README.md`)
- Request routing → Provider accounts: selects accounts (evidence: `internal/gateway/routing.go`)
- Request routing → Provider requests: forwards requests
- Provider requests → Model services: calls model API (evidence: `README.md`)
- Request routing → Gateway plugins: supports plugins
- Agent clients → Model services: uses models directly
- CLI commands → Agent config adapters: changes agent model (evidence: `internal/cli/main.go`)
- CLI commands → Preferences: loads preferences (evidence: `internal/cli/main.go`)
- CLI commands → Profiles: manages profiles (evidence: `internal/cli/main.go`)
- CLI commands → Provider accounts: manages providers (evidence: `internal/cli/main.go`)
- CLI commands → Model catalog: reads catalog (evidence: `internal/cli/main.go`)
- Desktop app → Preferences: loads preferences (evidence: `internal/gui/app.go`)
- Desktop app → Agent config adapters: manages agents (evidence: `internal/gui/app.go`)
- Desktop app → Skills library: opens library (evidence: `internal/gui/app.go`)
- Terminal UI → Provider accounts: edits routing groups (evidence: `internal/tui/routing.go`)
- Model catalog → Preferences: reads preferences (evidence: `internal/codexcat/codexcat.go`)
- Request routing → Usage records: records usage (evidence: `internal/gateway/routing.go`)
- Session history → Provider accounts: uses provider data (evidence: `internal/sessions/sessions.go`)
- Image and MCP tools → Local gateway: uses gateway (evidence: `internal/imagemcp/imagemcp.go`)
- Image and MCP tools → Preferences: reads preferences (evidence: `internal/imagemcp/imagemcp.go`)
- MCP sign-in relay → Local gateway: relays MCP requests (evidence: `internal/mcpauth/mcpauth.go`)
- Desktop app → Session history: shows sessions
- CLI commands → Backup and sync: runs sync (evidence: `internal/cli/main.go`)
- Backup and sync → Provider accounts: backs up provider data (evidence: `internal/davsync/davsync.go`)
- Backup and sync → Skills library: backs up library (evidence: `internal/davsync/davsync.go`)