# openpetshq/openpets architecture

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

- Interactive diagram: https://gitdiagram.com/openpetshq/openpets
- Repository: https://github.com/openpetshq/openpets

## Overview

OpenPets is a desktop companion platform: users launch the app to get an animated pet, then manage pets and enable plugins; optional local agent integrations can trigger pet reactions. The map preserves the documented plugin SDK, catalog, pet-management, voice, and team check-in capabilities. Several subsystem paths are exact enclosing directories because their implementation files were not sampled; dashed edges mark relationships not verified in the excerpts.

Main entry points: [`apps/desktop/src/plugin-runtime.ts`](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/plugin-runtime.ts) (Plugin runtime), [`apps/desktop/src/pet-window.ts`](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/pet-window.ts) (Pet windows), [`apps/desktop/src/main.ts`](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/main.ts) (Desktop app), [`apps/desktop/src/renderer/src/main.tsx`](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/renderer/src/main.tsx) (Control Center)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_desktop_app["Desktop app<br/>[main.ts]"]
  node_control_center["Control Center<br/>[main.tsx]"]
  node_app_state[("App state<br/>[app-state.ts]")]
  node_team_checkins["Team check-ins"]
end

subgraph group_pets["Pet runtime"]
  node_pet_windows["Pet windows<br/>[pet-window.ts]"]
  node_pet_motion["Pet motion"]
  node_pet_chat["Pet chat"]
  node_pet_activities["Pet activities<br/>[pet-activities.ts]"]
  node_pet_packages["Pet packages<br/>[package.ts]"]
end

subgraph group_plugins["Plugin platform"]
  node_plugin_catalog["Plugin catalog<br/>[plugin-catalog.ts]"]
  node_plugin_runtime["Plugin runtime<br/>[plugin-runtime.ts]"]
  node_plugin_sdk["Plugin SDK<br/>[index.ts]"]
  node_official_plugins["Official plugins"]
end

subgraph group_integrations["Integrations"]
  node_agent_clients["Agent clients<br/>[index.ts]"]
  node_mcp_server["MCP server<br/>[server.ts]"]
  node_agent_setup["Agent setup<br/>[agent-setup.ts]"]
  node_voice_assistant["Voice assistant"]
  node_teams_ui["Teams UI"]
end

node_user(("User"))
node_agent(("Coding agent"))

node_user -->|"launches"| node_desktop_app
node_desktop_app -.->|"shows pets"| node_pet_windows
node_user -->|"manages pets"| node_control_center
node_control_center -.->|"configures plugins"| node_plugin_catalog
node_app_state -->|"validates packages"| node_pet_packages
node_pet_motion -->|"moves windows"| node_pet_windows
node_pet_chat -->|"reads check-in state"| node_team_checkins
node_plugin_sdk -.->|"provides APIs"| node_plugin_runtime
node_plugin_runtime -.->|"controls pets"| node_pet_windows
node_official_plugins -.->|"runs in"| node_plugin_runtime
node_agent -->|"invokes tools"| node_mcp_server
node_mcp_server -.->|"uses client"| node_agent_clients
node_agent_setup -.->|"configures access"| node_agent_clients
node_voice_assistant -.->|"supports conversation"| node_pet_chat
node_teams_ui -.->|"manages check-ins"| node_team_checkins

click node_desktop_app "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/main.ts"
click node_control_center "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/renderer/src/main.tsx"
click node_app_state "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/app-state.ts"
click node_team_checkins "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/manager-check-in-service.ts"
click node_pet_windows "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/pet-window.ts"
click node_pet_motion "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/pet-motion-engine.ts"
click node_pet_chat "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/default-pet-chat.ts"
click node_pet_activities "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/pet-activities.ts"
click node_pet_packages "https://github.com/openpetshq/openpets/blob/main/packages/pet-format/src/package.ts"
click node_plugin_catalog "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/plugin-catalog.ts"
click node_plugin_runtime "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/plugin-runtime.ts"
click node_plugin_sdk "https://github.com/openpetshq/openpets/blob/main/packages/sdk/src/index.ts"
click node_official_plugins "https://github.com/openpetshq/openpets/tree/main/plugins/official"
click node_agent_clients "https://github.com/openpetshq/openpets/blob/main/packages/client/src/index.ts"
click node_mcp_server "https://github.com/openpetshq/openpets/blob/main/packages/mcp/src/server.ts"
click node_agent_setup "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/agent-setup.ts"
click node_voice_assistant "https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/voice-assistant-host.ts"
click node_teams_ui "https://github.com/openpetshq/openpets/tree/main/apps/desktop/src/renderer/src/teams"

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_desktop_app,node_control_center,node_app_state,node_team_checkins,node_user toneBlue
class node_pet_windows,node_pet_motion,node_pet_chat,node_pet_activities,node_pet_packages toneAmber
class node_plugin_catalog,node_plugin_runtime,node_plugin_sdk,node_official_plugins toneMint
class node_agent_clients,node_mcp_server,node_agent_setup,node_voice_assistant,node_teams_ui toneRose
class node_agent toneIndigo
```

## Components

### Desktop experience

- [Desktop app](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/main.ts): `apps/desktop/src/main.ts`
- [Control Center](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/renderer/src/main.tsx): `apps/desktop/src/renderer/src/main.tsx`
- [App state](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/app-state.ts): `apps/desktop/src/app-state.ts`
- [Team check-ins](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/manager-check-in-service.ts): `apps/desktop/src/manager-check-in-service.ts`

### Pet runtime

- [Pet windows](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/pet-window.ts): `apps/desktop/src/pet-window.ts`
- [Pet motion](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/pet-motion-engine.ts): `apps/desktop/src/pet-motion-engine.ts`
- [Pet chat](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/default-pet-chat.ts): `apps/desktop/src/default-pet-chat.ts`
- [Pet activities](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/pet-activities.ts): `apps/desktop/src/pet-activities.ts`
- [Pet packages](https://github.com/openpetshq/openpets/blob/main/packages/pet-format/src/package.ts): `packages/pet-format/src/package.ts`

### Plugin platform

- [Plugin catalog](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/plugin-catalog.ts): `apps/desktop/src/plugin-catalog.ts`
- [Plugin runtime](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/plugin-runtime.ts): `apps/desktop/src/plugin-runtime.ts`
- [Plugin SDK](https://github.com/openpetshq/openpets/blob/main/packages/sdk/src/index.ts): `packages/sdk/src/index.ts`
- [Official plugins](https://github.com/openpetshq/openpets/tree/main/plugins/official): `plugins/official`

### Integrations

- [Agent clients](https://github.com/openpetshq/openpets/blob/main/packages/client/src/index.ts): `packages/client/src/index.ts`
- [MCP server](https://github.com/openpetshq/openpets/blob/main/packages/mcp/src/server.ts): `packages/mcp/src/server.ts`
- [Agent setup](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/agent-setup.ts): `apps/desktop/src/agent-setup.ts`
- [Voice assistant](https://github.com/openpetshq/openpets/blob/main/apps/desktop/src/voice-assistant-host.ts): `apps/desktop/src/voice-assistant-host.ts`
- [Teams UI](https://github.com/openpetshq/openpets/tree/main/apps/desktop/src/renderer/src/teams): `apps/desktop/src/renderer/src/teams`

### Other components

- **User**
- **Coding agent**

## Connections

- User → Desktop app: launches (evidence: `README.md`)
- Desktop app → Pet windows: shows pets
- User → Control Center: manages pets (evidence: `README.md`)
- Control Center → Plugin catalog: configures plugins
- App state → Pet packages: validates packages (evidence: `apps/desktop/src/app-state.ts`)
- Pet motion → Pet windows: moves windows (evidence: `apps/desktop/src/pet-motion-engine.ts`)
- Pet chat → Team check-ins: reads check-in state (evidence: `apps/desktop/src/default-pet-chat.ts`)
- Plugin SDK → Plugin runtime: provides APIs
- Plugin runtime → Pet windows: controls pets
- Official plugins → Plugin runtime: runs in
- Coding agent → MCP server: invokes tools (evidence: `README.md`)
- MCP server → Agent clients: uses client
- Agent setup → Agent clients: configures access
- Voice assistant → Pet chat: supports conversation (evidence: `apps/desktop/src/default-pet-chat.ts`)
- Teams UI → Team check-ins: manages check-ins
