# agentprojectcontext/apx architecture

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

- Interactive diagram: https://gitdiagram.com/agentprojectcontext/apx
- Repository: https://github.com/agentprojectcontext/apx

## Overview

APX is a local-first home for AI-agent teams, exposed through desktop, web, phone, and messaging interfaces. The main workflow is an owner request entering a thread, becoming a durable run, executing an agent turn with tools or delegation, and reporting the outcome. Other documented product branches include project crews, tasks, routines, memory, browser/computer use, integrations, and widgets. Some connections below come from README claims or indexed imports; unsampled implementation details are not inferred.

Main entry points: [`apps/core/src/engine/engine.ts`](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/engine/engine.ts) (Agent turn engine), [`apps/core/src/engine/turn.ts`](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/engine/turn.ts) (Turn execution), [`apps/core/src/tools/types.ts`](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/tools/types.ts) (Agent tools), [`apps/core/src/domain/store.ts`](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/domain/store.ts) (Domain store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["Owner interfaces"]
  node_desktop["Desktop app<br/>[main.ts]"]
  node_mobile["Phone app<br/>[App.tsx]"]
  node_web["Web panel<br/>[App.tsx]"]
  node_channels["Messaging channels<br/>[manager.ts]"]
end

subgraph group_orchestration["Agent orchestration"]
  node_core["Core service<br/>[server.ts]"]
  node_engine["Agent turn engine<br/>[engine.ts]"]
  node_turn["Turn execution<br/>[turn.ts]"]
  node_delegation["Agent delegation<br/>[delegation.ts]"]
end

subgraph group_work["Work and memory"]
  node_teams["Project agents<br/>[agents.ts]"]
  node_tasks["Tasks and commitments<br/>[tasks.ts]"]
  node_routines["Scheduled routines<br/>[routines.ts]"]
  node_memory["Agent memory<br/>[memory-capture.ts]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_tools["Agent tools<br/>[types.ts]"]
  node_browser["Browser and computer<br/>[browser.ts]"]
  node_models["Model providers<br/>[registry.ts]"]
  node_harness["CLI harnesses<br/>[env.ts]"]
  node_integrations["External integrations<br/>[catalog.ts]"]
  node_surfaces["Widgets and apps<br/>[widget-kit.ts]"]
end

subgraph group_persistence["Persistence"]
  node_runs[("Durable runs<br/>[runs.ts]")]
  node_store["Domain store<br/>[store.ts]"]
  node_db[("SQLite database<br/>[db.ts]")]
end

node_owner(("Owner"))

node_owner -->|"uses"| node_desktop
node_owner -->|"uses"| node_mobile
node_owner -->|"uses"| node_web
node_owner -->|"messages"| node_channels
node_desktop -->|"connects to"| node_core
node_mobile -->|"pairs with"| node_core
node_web -.->|"uses"| node_core
node_channels -->|"starts turns"| node_engine
node_engine -->|"queues turns"| node_runs
node_engine -->|"runs turn"| node_turn
node_engine -->|"creates delegations"| node_delegation
node_engine -->|"uses"| node_store
node_store -->|"uses"| node_db
node_store -->|"provides repository"| node_runs
node_turn -.->|"uses"| node_tools
node_turn -.->|"requests completion"| node_models
node_turn -.->|"runs sessions"| node_harness
node_tools -->|"includes"| node_browser
node_tools -.->|"accesses"| node_integrations
node_delegation -->|"delegates to"| node_teams
node_owner -->|"assigns work"| node_tasks
node_owner -->|"schedules work"| node_routines
node_turn -.->|"learns from turns"| node_memory
node_owner -->|"requests widgets"| node_surfaces

click node_desktop "https://github.com/agentprojectcontext/apx/blob/main/apps/desktop/src/main/main.ts"
click node_mobile "https://github.com/agentprojectcontext/apx/blob/main/apps/mobile/src/App.tsx"
click node_web "https://github.com/agentprojectcontext/apx/blob/main/apps/web/src/App.tsx"
click node_channels "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/channels/manager.ts"
click node_core "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/server.ts"
click node_engine "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/engine/engine.ts"
click node_turn "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/engine/turn.ts"
click node_delegation "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/engine/delegation.ts"
click node_runs "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/domain/runs.ts"
click node_store "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/domain/store.ts"
click node_db "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/db/db.ts"
click node_teams "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/domain/agents.ts"
click node_tasks "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/domain/tasks.ts"
click node_routines "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/domain/routines.ts"
click node_memory "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/engine/memory-capture.ts"
click node_tools "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/tools/types.ts"
click node_browser "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/tools/browser.ts"
click node_models "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/providers/registry.ts"
click node_harness "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/harness/env.ts"
click node_integrations "https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/integrations/catalog.ts"
click node_surfaces "https://github.com/agentprojectcontext/apx/blob/main/packages/surfaces/src/widget-kit.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_desktop,node_mobile,node_web,node_channels toneBlue
class node_core,node_engine,node_turn,node_delegation toneAmber
class node_teams,node_tasks,node_routines,node_memory toneMint
class node_tools,node_browser,node_models,node_harness,node_integrations,node_surfaces toneRose
class node_runs,node_store,node_db,node_owner toneIndigo
```

## Components

### Owner interfaces

- [Desktop app](https://github.com/agentprojectcontext/apx/blob/main/apps/desktop/src/main/main.ts): `apps/desktop/src/main/main.ts`
- [Phone app](https://github.com/agentprojectcontext/apx/blob/main/apps/mobile/src/App.tsx): `apps/mobile/src/App.tsx`
- [Web panel](https://github.com/agentprojectcontext/apx/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Messaging channels](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/channels/manager.ts): `apps/core/src/channels/manager.ts`

### Agent orchestration

- [Core service](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/server.ts): `apps/core/src/server.ts`
- [Agent turn engine](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/engine/engine.ts): `apps/core/src/engine/engine.ts`
- [Turn execution](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/engine/turn.ts): `apps/core/src/engine/turn.ts`
- [Agent delegation](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/engine/delegation.ts): `apps/core/src/engine/delegation.ts`

### Work and memory

- [Project agents](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/domain/agents.ts): `apps/core/src/domain/agents.ts`
- [Tasks and commitments](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/domain/tasks.ts): `apps/core/src/domain/tasks.ts`
- [Scheduled routines](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/domain/routines.ts): `apps/core/src/domain/routines.ts`
- [Agent memory](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/engine/memory-capture.ts): `apps/core/src/engine/memory-capture.ts`

### Agent capabilities

- [Agent tools](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/tools/types.ts): `apps/core/src/tools/types.ts`
- [Browser and computer](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/tools/browser.ts): `apps/core/src/tools/browser.ts`
- [Model providers](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/providers/registry.ts): `apps/core/src/providers/registry.ts`
- [CLI harnesses](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/harness/env.ts): `apps/core/src/harness/env.ts`
- [External integrations](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/integrations/catalog.ts): `apps/core/src/integrations/catalog.ts`
- [Widgets and apps](https://github.com/agentprojectcontext/apx/blob/main/packages/surfaces/src/widget-kit.ts): `packages/surfaces/src/widget-kit.ts`

### Persistence

- [Durable runs](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/domain/runs.ts): `apps/core/src/domain/runs.ts`
- [Domain store](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/domain/store.ts): `apps/core/src/domain/store.ts`
- [SQLite database](https://github.com/agentprojectcontext/apx/blob/main/apps/core/src/db/db.ts): `apps/core/src/db/db.ts`

### Other components

- **Owner**

## Connections

- Owner → Desktop app: uses (evidence: `README.md`)
- Owner → Phone app: uses (evidence: `README.md`)
- Owner → Web panel: uses (evidence: `README.md`)
- Owner → Messaging channels: messages (evidence: `README.md`)
- Desktop app → Core service: connects to (evidence: `README.md`)
- Phone app → Core service: pairs with (evidence: `README.md`)
- Web panel → Core service: uses
- Messaging channels → Agent turn engine: starts turns (evidence: `apps/core/src/channels/manager.ts`)
- Agent turn engine → Durable runs: queues turns (evidence: `apps/core/src/engine/engine.ts`)
- Agent turn engine → Turn execution: runs turn (evidence: `apps/core/src/engine/engine.ts`)
- Agent turn engine → Agent delegation: creates delegations (evidence: `apps/core/src/engine/engine.ts`)
- Agent turn engine → Domain store: uses (evidence: `apps/core/src/engine/engine.ts`)
- Domain store → SQLite database: uses (evidence: `apps/core/src/domain/store.ts`)
- Domain store → Durable runs: provides repository (evidence: `apps/core/src/domain/store.ts`)
- Turn execution → Agent tools: uses
- Turn execution → Model providers: requests completion
- Turn execution → CLI harnesses: runs sessions
- Agent tools → Browser and computer: includes (evidence: `README.md`)
- Agent tools → External integrations: accesses
- Agent delegation → Project agents: delegates to (evidence: `README.md`)
- Owner → Tasks and commitments: assigns work (evidence: `README.md`)
- Owner → Scheduled routines: schedules work (evidence: `README.md`)
- Turn execution → Agent memory: learns from turns
- Owner → Widgets and apps: requests widgets (evidence: `README.md`)
