# yc-software/qm architecture

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

- Interactive diagram: https://gitdiagram.com/yc-software/qm
- Repository: https://github.com/yc-software/qm

## Overview

QM is a self-hosted multiplayer agent harness: a person starts work in Slack or the web app, the shared core runs a turn through a selectable harness and model, and tools can execute in an isolated scope sandbox. The graph also preserves documented admin, memory, skills, web-app deployment, and background-work capabilities. The README documents the main service boundaries; sampled source and the SOURCE INDEX support several internal links. Some feature implementations were not sampled, so uncertain connections are omitted.

Main entry points: [`src/core/orchestrator.ts`](https://github.com/yc-software/qm/blob/main/src/core/orchestrator.ts) (Turn orchestrator), [`src/api/server.ts`](https://github.com/yc-software/qm/blob/main/src/api/server.ts) (HTTP API), [`src/harness/harness-router.ts`](https://github.com/yc-software/qm/blob/main/src/harness/harness-router.ts) (Harness router), [`src/resolution/resolution-service.ts`](https://github.com/yc-software/qm/blob/main/src/resolution/resolution-service.ts) (Scope policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_slack["Slack plugin<br/>[turn-handler.ts]"]
  node_web["Web app<br/>[main.ts]"]
end

subgraph group_runtime["Agent runtime"]
  node_api["HTTP API<br/>[server.ts]"]
  node_routes["API routes<br/>[route.ts]"]
  node_orchestrator["Turn orchestrator<br/>[orchestrator.ts]"]
  node_harness["Harness router<br/>[harness-router.ts]"]
  node_models["Model providers<br/>[pi-models.ts]"]
  node_sandbox["Scope sandbox<br/>[sandbox.ts]"]
end

subgraph group_identity["Identity and policy"]
  node_auth["Identity and auth"]
  node_policy["Scope policy"]
  node_admin["Admin controls<br/>[admin-service.ts]"]
end

subgraph group_workspace["Workspace capabilities"]
  node_sessions[("Sessions<br/>[session-store.ts]")]
  node_memory["Scoped memory<br/>[memory-service.ts]"]
  node_skills["Shared skills"]
  node_deployments["Web app deployments<br/>[deploy-service.ts]"]
end

subgraph group_operations["Background and operations"]
  node_background["Background work<br/>[runtime.ts]"]
  node_loops["Scheduled watches<br/>[runner.ts]"]
  node_webhooks["Inbound webhooks"]
  node_postgres[("Postgres<br/>[pg-pool.ts]")]
  node_deployment["Org deployment<br/>[infra.ts]"]
end

node_person(("People"))

node_person -->|"messages"| node_slack
node_person -->|"uses"| node_web
node_slack -->|"calls core"| node_api
node_web -->|"uses API"| node_api
node_api -->|"dispatches"| node_routes
node_routes -->|"authenticates"| node_auth
node_api -->|"serves turns"| node_orchestrator
node_orchestrator -->|"selects harness"| node_harness
node_harness -->|"selects model"| node_models
node_orchestrator -->|"runs tools"| node_sandbox
node_orchestrator -.->|"records history"| node_sessions
node_api -->|"persists state"| node_postgres
node_orchestrator -->|"resolves scope"| node_policy
node_policy -->|"checks posture"| node_auth
node_orchestrator -.->|"uses memory"| node_memory
node_admin -.->|"sets controls"| node_policy
node_admin -.->|"chooses harnesses"| node_harness
node_skills -.->|"imports packs"| node_deployment
node_person -.->|"publishes apps"| node_deployments
node_person -.->|"schedules work"| node_background
node_person -.->|"configures watches"| node_loops
node_person -.->|"sends events"| node_webhooks
node_background -.->|"stores state"| node_postgres
node_deployment -.->|"deploys runtime"| node_api

click node_slack "https://github.com/yc-software/qm/blob/main/src/slack/turn-handler.ts"
click node_web "https://github.com/yc-software/qm/blob/main/plugins/web-ui/src/main.ts"
click node_api "https://github.com/yc-software/qm/blob/main/src/api/server.ts"
click node_routes "https://github.com/yc-software/qm/blob/main/src/api/routes/route.ts"
click node_orchestrator "https://github.com/yc-software/qm/blob/main/src/core/orchestrator.ts"
click node_harness "https://github.com/yc-software/qm/blob/main/src/harness/harness-router.ts"
click node_models "https://github.com/yc-software/qm/blob/main/src/model/pi-models.ts"
click node_sandbox "https://github.com/yc-software/qm/blob/main/src/sandbox/sandbox.ts"
click node_auth "https://github.com/yc-software/qm/blob/main/src/auth/capability-token.ts"
click node_policy "https://github.com/yc-software/qm/blob/main/src/resolution/resolution-service.ts"
click node_sessions "https://github.com/yc-software/qm/blob/main/src/sessions/session-store.ts"
click node_memory "https://github.com/yc-software/qm/blob/main/src/memory/memory-service.ts"
click node_skills "https://github.com/yc-software/qm/blob/main/src/skills/skill-sync-engine.ts"
click node_deployments "https://github.com/yc-software/qm/blob/main/src/deploy/deploy-service.ts"
click node_admin "https://github.com/yc-software/qm/blob/main/src/admin/admin-service.ts"
click node_background "https://github.com/yc-software/qm/blob/main/src/cron/runtime.ts"
click node_loops "https://github.com/yc-software/qm/blob/main/src/loops/runner.ts"
click node_webhooks "https://github.com/yc-software/qm/blob/main/src/webhooks/webhook-receiver.ts"
click node_postgres "https://github.com/yc-software/qm/blob/main/src/persistence/pg-pool.ts"
click node_deployment "https://github.com/yc-software/qm/blob/main/cli/src/commands/infra.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_slack,node_web toneBlue
class node_api,node_routes,node_orchestrator,node_harness,node_models,node_sandbox toneAmber
class node_auth,node_policy,node_admin toneMint
class node_sessions,node_memory,node_skills,node_deployments toneRose
class node_background,node_loops,node_webhooks,node_postgres,node_deployment,node_person toneIndigo
```

## Components

### User surfaces

- [Slack plugin](https://github.com/yc-software/qm/blob/main/src/slack/turn-handler.ts): `src/slack/turn-handler.ts`
- [Web app](https://github.com/yc-software/qm/blob/main/plugins/web-ui/src/main.ts): `plugins/web-ui/src/main.ts`

### Agent runtime

- [HTTP API](https://github.com/yc-software/qm/blob/main/src/api/server.ts): `src/api/server.ts`
- [API routes](https://github.com/yc-software/qm/blob/main/src/api/routes/route.ts): `src/api/routes/route.ts`
- [Turn orchestrator](https://github.com/yc-software/qm/blob/main/src/core/orchestrator.ts): `src/core/orchestrator.ts`
- [Harness router](https://github.com/yc-software/qm/blob/main/src/harness/harness-router.ts): `src/harness/harness-router.ts`
- [Model providers](https://github.com/yc-software/qm/blob/main/src/model/pi-models.ts): `src/model/pi-models.ts`
- [Scope sandbox](https://github.com/yc-software/qm/blob/main/src/sandbox/sandbox.ts): `src/sandbox/sandbox.ts`

### Identity and policy

- [Identity and auth](https://github.com/yc-software/qm/blob/main/src/auth/capability-token.ts): `src/auth/capability-token.ts`
- [Scope policy](https://github.com/yc-software/qm/blob/main/src/resolution/resolution-service.ts): `src/resolution/resolution-service.ts`
- [Admin controls](https://github.com/yc-software/qm/blob/main/src/admin/admin-service.ts): `src/admin/admin-service.ts`

### Workspace capabilities

- [Sessions](https://github.com/yc-software/qm/blob/main/src/sessions/session-store.ts): `src/sessions/session-store.ts`
- [Scoped memory](https://github.com/yc-software/qm/blob/main/src/memory/memory-service.ts): `src/memory/memory-service.ts`
- [Shared skills](https://github.com/yc-software/qm/blob/main/src/skills/skill-sync-engine.ts): `src/skills/skill-sync-engine.ts`
- [Web app deployments](https://github.com/yc-software/qm/blob/main/src/deploy/deploy-service.ts): `src/deploy/deploy-service.ts`

### Background and operations

- [Background work](https://github.com/yc-software/qm/blob/main/src/cron/runtime.ts): `src/cron/runtime.ts`
- [Scheduled watches](https://github.com/yc-software/qm/blob/main/src/loops/runner.ts): `src/loops/runner.ts`
- [Inbound webhooks](https://github.com/yc-software/qm/blob/main/src/webhooks/webhook-receiver.ts): `src/webhooks/webhook-receiver.ts`
- [Postgres](https://github.com/yc-software/qm/blob/main/src/persistence/pg-pool.ts): `src/persistence/pg-pool.ts`
- [Org deployment](https://github.com/yc-software/qm/blob/main/cli/src/commands/infra.ts): `cli/src/commands/infra.ts`

### Other components

- **People**

## Connections

- People → Slack plugin: messages
- People → Web app: uses
- Slack plugin → HTTP API: calls core
- Web app → HTTP API: uses API
- HTTP API → API routes: dispatches (evidence: `src/api/server.ts`)
- API routes → Identity and auth: authenticates (evidence: `src/api/routes/route.ts`)
- HTTP API → Turn orchestrator: serves turns
- Turn orchestrator → Harness router: selects harness (evidence: `src/core/orchestrator.ts`)
- Harness router → Model providers: selects model (evidence: `src/harness/harness-router.ts`)
- Turn orchestrator → Scope sandbox: runs tools (evidence: `src/core/orchestrator.ts`)
- Turn orchestrator → Sessions: records history (evidence: `src/core/orchestrator.ts`)
- HTTP API → Postgres: persists state
- Turn orchestrator → Scope policy: resolves scope (evidence: `src/core/orchestrator.ts`)
- Scope policy → Identity and auth: checks posture (evidence: `src/resolution/resolution-service.ts`)
- Turn orchestrator → Scoped memory: uses memory
- Admin controls → Scope policy: sets controls
- Admin controls → Harness router: chooses harnesses
- Shared skills → Org deployment: imports packs
- People → Web app deployments: publishes apps
- People → Background work: schedules work
- People → Scheduled watches: configures watches
- People → Inbound webhooks: sends events
- Background work → Postgres: stores state
- Org deployment → HTTP API: deploys runtime