# x-t-e-r/openpet architecture

> Architecture diagram of the GitHub repository x-t-e-r/openpet, 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/x-t-e-r/openpet
- Repository: https://github.com/x-t-e-r/openpet
- Video tour (about a minute): https://gitdiagram.com/x-t-e-r/openpet/video

## Overview

OpenPet is a local desktop-pet runtime: users configure a companion, import compatible pet packs, and see it react to clicks, movement, and agent progress. The main path runs from an agent or user through the local HTTP API or settings UI, into Tauri runtime state, then to the pet window and its animation. The README also documents CLI and MCP control, website import, event reactions, and configurable storage. Source excerpts clarify UI and API calls; some Rust runtime wiring and import details are only partially shown.

Main entry points: [`src/PetWindow.tsx`](https://github.com/x-t-e-r/openpet/blob/master/src/PetWindow.tsx) (Pet window), [`src-tauri/src/lib.rs`](https://github.com/x-t-e-r/openpet/blob/master/src-tauri/src/lib.rs) (Tauri runtime), [`src/SettingsPage.tsx`](https://github.com/x-t-e-r/openpet/blob/master/src/SettingsPage.tsx) (Settings UI), [`src-tauri/src/http_api.rs`](https://github.com/x-t-e-r/openpet/blob/master/src-tauri/src/http_api.rs) (Local HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop experience"]
  node_settings["Settings UI<br/>[SettingsPage.tsx]"]
  node_pet_window["Pet window<br/>[PetWindow.tsx]"]
  node_app_router["Window router<br/>[App.tsx]"]
end

subgraph group_pet["Pet behavior"]
  node_pet_catalog["Pet catalog<br/>[catalog.ts]"]
  node_pet_settings["Settings model<br/>[settings.ts]"]
  node_animation["Animation engine<br/>[animation.ts]"]
  node_motion["Walking motion<br/>[motion.ts]"]
  node_companion_events["Event mapping<br/>[events.ts]"]
  node_sprite["Sprite renderer<br/>[PetSprite.tsx]"]
end

subgraph group_runtime["Runtime and imports"]
  node_runtime_state["Tauri runtime<br/>[lib.rs]"]
  node_http_api["Local HTTP API<br/>[http_api.rs]"]
  node_pet_assets["Bundled pet assets"]
end

subgraph group_agents["Agent interfaces"]
  node_cli["OpenPet CLI<br/>[openpet_cli.py]"]
  node_mcp["MCP bridge"]
end

node_user(("Desktop user"))
node_agent(("Local agent"))
node_gallery["Pet websites"]

node_user -->|"configures"| node_settings
node_user -->|"interacts with"| node_pet_window
node_agent -->|"uses"| node_cli
node_agent -->|"uses"| node_mcp
node_agent -->|"controls via HTTP"| node_http_api
node_cli -->|"calls localhost"| node_http_api
node_mcp -->|"calls runtime API"| node_http_api
node_settings -->|"invokes commands"| node_runtime_state
node_settings -->|"uses settings model"| node_pet_settings
node_settings -->|"uses catalog"| node_pet_catalog
node_settings -->|"validates events"| node_companion_events
node_http_api -->|"dispatches actions"| node_runtime_state
node_http_api -->|"requests imports"| node_runtime_state
node_runtime_state -.->|"emits runtime events"| node_pet_window
node_runtime_state -.->|"provides snapshot"| node_pet_catalog
node_runtime_state -.->|"loads bundled packs"| node_pet_assets
node_gallery -->|"provides import source"| node_runtime_state
node_pet_window -->|"resolves walking"| node_motion
node_pet_window -->|"uses dimensions"| node_animation
node_pet_window -->|"reads preferences"| node_pet_settings
node_pet_window -->|"renders"| node_sprite
node_sprite -->|"uses frames"| node_animation
node_sprite -->|"reads pet sheet"| node_pet_catalog
node_pet_settings -->|"uses catalog defaults"| node_pet_catalog
node_companion_events -->|"maps event actions"| node_animation
node_app_router -->|"selects pet view"| node_pet_window
node_app_router -->|"selects settings view"| node_settings

click node_settings "https://github.com/x-t-e-r/openpet/blob/master/src/SettingsPage.tsx"
click node_pet_window "https://github.com/x-t-e-r/openpet/blob/master/src/PetWindow.tsx"
click node_app_router "https://github.com/x-t-e-r/openpet/blob/master/src/App.tsx"
click node_runtime_state "https://github.com/x-t-e-r/openpet/blob/master/src-tauri/src/lib.rs"
click node_http_api "https://github.com/x-t-e-r/openpet/blob/master/src-tauri/src/http_api.rs"
click node_pet_catalog "https://github.com/x-t-e-r/openpet/blob/master/src/pet/catalog.ts"
click node_pet_settings "https://github.com/x-t-e-r/openpet/blob/master/src/pet/settings.ts"
click node_animation "https://github.com/x-t-e-r/openpet/blob/master/src/pet/animation.ts"
click node_motion "https://github.com/x-t-e-r/openpet/blob/master/src/pet/motion.ts"
click node_companion_events "https://github.com/x-t-e-r/openpet/blob/master/src/pet/events.ts"
click node_sprite "https://github.com/x-t-e-r/openpet/blob/master/src/pet/PetSprite.tsx"
click node_cli "https://github.com/x-t-e-r/openpet/blob/master/skills/openpet-cli/scripts/openpet_cli.py"
click node_mcp "https://github.com/x-t-e-r/openpet/blob/master/skills/openpet-mcp/scripts/openpet_mcp_server.py"
click node_pet_assets "https://github.com/x-t-e-r/openpet/tree/master/public/pets"

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_settings,node_pet_window,node_app_router,node_user toneBlue
class node_pet_catalog,node_pet_settings,node_animation,node_motion,node_companion_events,node_sprite toneAmber
class node_runtime_state,node_http_api,node_pet_assets toneMint
class node_cli,node_mcp toneRose
class node_agent,node_gallery toneIndigo
```

## Components

### Desktop experience

- [Settings UI](https://github.com/x-t-e-r/openpet/blob/master/src/SettingsPage.tsx): `src/SettingsPage.tsx`
- [Pet window](https://github.com/x-t-e-r/openpet/blob/master/src/PetWindow.tsx): `src/PetWindow.tsx`
- [Window router](https://github.com/x-t-e-r/openpet/blob/master/src/App.tsx): `src/App.tsx`

### Pet behavior

- [Pet catalog](https://github.com/x-t-e-r/openpet/blob/master/src/pet/catalog.ts): `src/pet/catalog.ts`
- [Settings model](https://github.com/x-t-e-r/openpet/blob/master/src/pet/settings.ts): `src/pet/settings.ts`
- [Animation engine](https://github.com/x-t-e-r/openpet/blob/master/src/pet/animation.ts): `src/pet/animation.ts`
- [Walking motion](https://github.com/x-t-e-r/openpet/blob/master/src/pet/motion.ts): `src/pet/motion.ts`
- [Event mapping](https://github.com/x-t-e-r/openpet/blob/master/src/pet/events.ts): `src/pet/events.ts`
- [Sprite renderer](https://github.com/x-t-e-r/openpet/blob/master/src/pet/PetSprite.tsx): `src/pet/PetSprite.tsx`

### Runtime and imports

- [Tauri runtime](https://github.com/x-t-e-r/openpet/blob/master/src-tauri/src/lib.rs): `src-tauri/src/lib.rs`
- [Local HTTP API](https://github.com/x-t-e-r/openpet/blob/master/src-tauri/src/http_api.rs): `src-tauri/src/http_api.rs`
- [Bundled pet assets](https://github.com/x-t-e-r/openpet/tree/master/public/pets): `public/pets`

### Agent interfaces

- [OpenPet CLI](https://github.com/x-t-e-r/openpet/blob/master/skills/openpet-cli/scripts/openpet_cli.py): `skills/openpet-cli/scripts/openpet_cli.py`
- [MCP bridge](https://github.com/x-t-e-r/openpet/blob/master/skills/openpet-mcp/scripts/openpet_mcp_server.py): `skills/openpet-mcp/scripts/openpet_mcp_server.py`

### Other components

- **Desktop user**
- **Local agent**
- **Pet websites**

## Connections

- Desktop user → Settings UI: configures (evidence: `README.md`)
- Desktop user → Pet window: interacts with (evidence: `README.md`)
- Local agent → OpenPet CLI: uses (evidence: `README.md`)
- Local agent → MCP bridge: uses (evidence: `README.md`)
- Local agent → Local HTTP API: controls via HTTP (evidence: `README.md`)
- OpenPet CLI → Local HTTP API: calls localhost (evidence: `README.md`)
- MCP bridge → Local HTTP API: calls runtime API (evidence: `README.md`)
- Settings UI → Tauri runtime: invokes commands (evidence: `src/SettingsPage.tsx`)
- Settings UI → Settings model: uses settings model (evidence: `src/SettingsPage.tsx`)
- Settings UI → Pet catalog: uses catalog (evidence: `src/SettingsPage.tsx`)
- Settings UI → Event mapping: validates events (evidence: `src/SettingsPage.tsx`)
- Local HTTP API → Tauri runtime: dispatches actions (evidence: `src-tauri/src/http_api.rs`)
- Local HTTP API → Tauri runtime: requests imports (evidence: `src-tauri/src/http_api.rs`)
- Tauri runtime → Pet window: emits runtime events
- Tauri runtime → Pet catalog: provides snapshot
- Tauri runtime → Bundled pet assets: loads bundled packs
- Pet websites → Tauri runtime: provides import source (evidence: `README.md`)
- Pet window → Walking motion: resolves walking (evidence: `src/PetWindow.tsx`)
- Pet window → Animation engine: uses dimensions (evidence: `src/PetWindow.tsx`)
- Pet window → Settings model: reads preferences (evidence: `src/PetWindow.tsx`)
- Pet window → Sprite renderer: renders (evidence: `src/PetWindow.tsx`)
- Sprite renderer → Animation engine: uses frames (evidence: `src/pet/PetSprite.tsx`)
- Sprite renderer → Pet catalog: reads pet sheet (evidence: `src/pet/PetSprite.tsx`)
- Settings model → Pet catalog: uses catalog defaults (evidence: `src/pet/settings.ts`)
- Event mapping → Animation engine: maps event actions (evidence: `src/pet/events.ts`)
- Window router → Pet window: selects pet view (evidence: `src/App.tsx`)
- Window router → Settings UI: selects settings view (evidence: `src/App.tsx`)
