# them1n9/perry architecture

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

- Interactive diagram: https://gitdiagram.com/them1n9/perry
- Repository: https://github.com/them1n9/perry

## Overview

Perry is a self-hosted personal AI assistant: a user messages it through the web dashboard, Telegram, or WhatsApp; a local server routes the conversation to a paired computer’s runner; and the runner invokes the selected coding-agent engine to work on that computer and return a response. Convex-style functions and a local data store support chat, memory, scheduling, connectors, approvals, and traces. The README documents product capabilities not fully evidenced in sampled source; those branches are shown at subsystem level, with links omitted where implementation wiring was not shown.

Main entry points: [`server/runtime.ts`](https://github.com/them1n9/perry/blob/main/server/runtime.ts) (Function runtime), [`runner/index.ts`](https://github.com/them1n9/perry/blob/main/runner/index.ts) (Computer runner), [`convex/lib/routing.ts`](https://github.com/them1n9/perry/blob/main/convex/lib/routing.ts) (Conversation routing), [`server/index.ts`](https://github.com/them1n9/perry/blob/main/server/index.ts) (Local server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_dashboard["Web dashboard"]
  node_messaging["Telegram / WhatsApp"]
  node_desktop["Desktop companion"]
  node_webclient["Web client API<br/>[backend.ts]"]
end

subgraph group_assistant["Assistant runtime"]
  node_server["Local server<br/>[index.ts]"]
  node_runtime["Function runtime<br/>[runtime.ts]"]
  node_runner["Computer runner<br/>[index.ts]"]
  node_engine["Agent engines"]
  node_tools["Computer tools<br/>[commands.ts]"]
end

subgraph group_capabilities["Assistant capabilities"]
  node_chat["Conversation routing<br/>[routing.ts]"]
  node_memory["Memory and Brain<br/>[brain.ts]"]
  node_work["Schedules and tasks<br/>[jobs.ts]"]
  node_connectors["Account connectors<br/>[composio.ts]"]
  node_approvals["Access approvals<br/>[approvals.ts]"]
  node_traces["Run traces<br/>[codex.ts]"]
end

subgraph group_persistence["Local backend"]
  node_data[("Assistant data<br/>[schema.ts]")]
  node_localfiles[("Local files<br/>[home.ts]")]
end

node_owner(("Owner"))
node_composio["Composio"]
node_selectedengine["Chosen engine"]

node_owner -->|"messages"| node_dashboard
node_owner -->|"messages"| node_messaging
node_owner -->|"speaks to"| node_desktop
node_dashboard -->|"calls"| node_webclient
node_webclient -->|"requests"| node_runtime
node_messaging -.->|"delivers messages"| node_server
node_desktop -.->|"uses assistant"| node_server
node_server -->|"starts"| node_runtime
node_runtime -.->|"reads and writes"| node_data
node_server -->|"pairs computer"| node_runner
node_runner -->|"runs turns"| node_engine
node_selectedengine -->|"selects"| node_engine
node_engine -.->|"uses tools"| node_tools
node_runtime -.->|"routes conversations"| node_chat
node_chat -.->|"dispatches work"| node_runner
node_runner -->|"works on computer"| node_localfiles
node_chat -.->|"uses memory"| node_memory
node_runtime -.->|"schedules jobs"| node_work
node_chat -.->|"reaches accounts"| node_connectors
node_connectors -->|"connects through"| node_composio
node_runtime -.->|"requests approval"| node_approvals
node_runner -->|"reports traces"| node_traces
node_runtime -.->|"persists assistant state"| node_data

click node_dashboard "https://github.com/them1n9/perry/tree/main/components/dashboard/screens"
click node_messaging "https://github.com/them1n9/perry/tree/main/server"
click node_desktop "https://github.com/them1n9/perry/tree/main/pet"
click node_webclient "https://github.com/them1n9/perry/blob/main/client/backend.ts"
click node_server "https://github.com/them1n9/perry/blob/main/server/index.ts"
click node_runtime "https://github.com/them1n9/perry/blob/main/server/runtime.ts"
click node_runner "https://github.com/them1n9/perry/blob/main/runner/index.ts"
click node_engine "https://github.com/them1n9/perry/tree/main/runner/engines"
click node_tools "https://github.com/them1n9/perry/blob/main/convex/lib/commands.ts"
click node_chat "https://github.com/them1n9/perry/blob/main/convex/lib/routing.ts"
click node_memory "https://github.com/them1n9/perry/blob/main/convex/brain.ts"
click node_work "https://github.com/them1n9/perry/blob/main/convex/jobs.ts"
click node_connectors "https://github.com/them1n9/perry/blob/main/convex/composio.ts"
click node_approvals "https://github.com/them1n9/perry/blob/main/convex/approvals.ts"
click node_traces "https://github.com/them1n9/perry/blob/main/convex/codex.ts"
click node_data "https://github.com/them1n9/perry/blob/main/convex/schema.ts"
click node_localfiles "https://github.com/them1n9/perry/blob/main/runner/home.ts"

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_dashboard,node_messaging,node_desktop,node_webclient toneBlue
class node_server,node_runtime,node_runner,node_engine,node_tools toneAmber
class node_chat,node_memory,node_work,node_connectors,node_approvals,node_traces toneMint
class node_data,node_localfiles toneRose
class node_owner,node_composio,node_selectedengine toneIndigo
```

## Components

### User interaction

- [Web dashboard](https://github.com/them1n9/perry/tree/main/components/dashboard/screens): `components/dashboard/screens`
- [Telegram / WhatsApp](https://github.com/them1n9/perry/tree/main/server): `server`
- [Desktop companion](https://github.com/them1n9/perry/tree/main/pet): `pet`
- [Web client API](https://github.com/them1n9/perry/blob/main/client/backend.ts): `client/backend.ts`

### Assistant runtime

- [Local server](https://github.com/them1n9/perry/blob/main/server/index.ts): `server/index.ts`
- [Function runtime](https://github.com/them1n9/perry/blob/main/server/runtime.ts): `server/runtime.ts`
- [Computer runner](https://github.com/them1n9/perry/blob/main/runner/index.ts): `runner/index.ts`
- [Agent engines](https://github.com/them1n9/perry/tree/main/runner/engines): `runner/engines`
- [Computer tools](https://github.com/them1n9/perry/blob/main/convex/lib/commands.ts): `convex/lib/commands.ts`

### Assistant capabilities

- [Conversation routing](https://github.com/them1n9/perry/blob/main/convex/lib/routing.ts): `convex/lib/routing.ts`
- [Memory and Brain](https://github.com/them1n9/perry/blob/main/convex/brain.ts): `convex/brain.ts`
- [Schedules and tasks](https://github.com/them1n9/perry/blob/main/convex/jobs.ts): `convex/jobs.ts`
- [Account connectors](https://github.com/them1n9/perry/blob/main/convex/composio.ts): `convex/composio.ts`
- [Access approvals](https://github.com/them1n9/perry/blob/main/convex/approvals.ts): `convex/approvals.ts`
- [Run traces](https://github.com/them1n9/perry/blob/main/convex/codex.ts): `convex/codex.ts`

### Local backend

- [Assistant data](https://github.com/them1n9/perry/blob/main/convex/schema.ts): `convex/schema.ts`
- [Local files](https://github.com/them1n9/perry/blob/main/runner/home.ts): `runner/home.ts`

### Other components

- **Owner**
- **Composio**
- **Chosen engine**

## Connections

- Owner → Web dashboard: messages (evidence: `README.md`)
- Owner → Telegram / WhatsApp: messages (evidence: `README.md`)
- Owner → Desktop companion: speaks to (evidence: `README.md`)
- Web dashboard → Web client API: calls
- Web client API → Function runtime: requests (evidence: `client/backend.ts`)
- Telegram / WhatsApp → Local server: delivers messages (evidence: `server/api.ts`)
- Desktop companion → Local server: uses assistant
- Local server → Function runtime: starts (evidence: `server/index.ts`)
- Function runtime → Assistant data: reads and writes
- Local server → Computer runner: pairs computer (evidence: `server/index.ts`)
- Computer runner → Agent engines: runs turns (evidence: `runner/index.ts`)
- Chosen engine → Agent engines: selects
- Agent engines → Computer tools: uses tools
- Function runtime → Conversation routing: routes conversations
- Conversation routing → Computer runner: dispatches work (evidence: `runner/index.ts`)
- Computer runner → Local files: works on computer (evidence: `README.md`)
- Conversation routing → Memory and Brain: uses memory
- Function runtime → Schedules and tasks: schedules jobs
- Conversation routing → Account connectors: reaches accounts
- Account connectors → Composio: connects through (evidence: `README.md`)
- Function runtime → Access approvals: requests approval
- Computer runner → Run traces: reports traces (evidence: `runner/index.ts`)
- Function runtime → Assistant data: persists assistant state