# sting8k/piggery architecture

> Architecture diagram of the GitHub repository sting8k/piggery, 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/sting8k/piggery
- Repository: https://github.com/sting8k/piggery

## Overview

Piggery coordinates coding-agent sessions through a local daemon: harness plugins connect to its Unix-socket protocol, while the daemon serves the core farm engine, which enforces team roles and routes mailbox work. Agents can be started as workers on their configured harness. Operators inspect and administer teams through the CLI; Paseo provides a farm view. The README documents SQLite-backed local operation and multiple harness integrations. Some links are based on the SOURCE INDEX or README rather than complete excerpts, so unsampled internals are represented only at subsystem level.

Main entry points: [`internal/server/server.go`](https://github.com/sting8k/piggery/blob/main/internal/server/server.go) (Socket daemon), [`internal/core/engine.go`](https://github.com/sting8k/piggery/blob/main/internal/core/engine.go) (Farm engine), [`extensions`](https://github.com/sting8k/piggery/tree/main/extensions) (Harness plugins), [`extensions/paseo/index.client.tsx`](https://github.com/sting8k/piggery/blob/main/extensions/paseo/index.client.tsx) (Paseo plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agents["Agent integrations"]
  node_harness["Harness plugins"]
  node_piadapter["Turn adapter<br/>[adapter.mjs]"]
  node_harnessclients["Socket clients<br/>[client.mjs]"]
  node_paseoplugin["Paseo plugin<br/>[index.client.tsx]"]
  node_paseoview["Paseo farm view<br/>[farm.tsx]"]
  node_paseodata["Paseo view model<br/>[view.ts]"]
end

subgraph group_runtime["Daemon runtime"]
  node_daemon["Socket daemon<br/>[server.go]"]
  node_protocol["JSON-line protocol<br/>[proto.go]"]
  node_workerdriver["Worker runner<br/>[runner.go]"]
  node_harnessdrivers["Harness drivers"]
  node_state[("SQLite state<br/>[store.go]")]
end

subgraph group_domain["Farm domain"]
  node_engine["Farm engine<br/>[engine.go]"]
  node_teams["Teams and roles"]
  node_mailbox["Mailbox and events<br/>[mail.go]"]
  node_manifests["Farm layouts<br/>[manifests.go]"]
end

subgraph group_operations["Operations and views"]
  node_cli["CLI"]
  node_top["Farm monitor<br/>[top.go]"]
  node_topview["Monitor rendering<br/>[topview.go]"]
end

node_agent(("Coding agent"))

node_agent -->|"uses harness"| node_harness
node_harness -->|"maps turns"| node_piadapter
node_harness -->|"calls daemon"| node_harnessclients
node_harnessclients -->|"sends requests"| node_daemon
node_daemon -->|"speaks protocol"| node_protocol
node_daemon -->|"dispatches calls"| node_engine
node_daemon -->|"uses storage"| node_state
node_daemon -->|"manages workers"| node_workerdriver
node_daemon -->|"loads layouts"| node_manifests
node_engine -.->|"enforces roles"| node_teams
node_engine -.->|"routes mail"| node_mailbox
node_workerdriver -->|"selects harness"| node_harnessdrivers
node_cli -->|"starts daemon"| node_daemon
node_cli -->|"queries farm"| node_engine
node_top -->|"renders monitor"| node_topview
node_paseoplugin -->|"registers view"| node_paseoview
node_paseoview -->|"builds display"| node_paseodata
node_paseoplugin -.->|"reads farm data"| node_daemon
node_agent -->|"exchanges mail"| node_mailbox
node_manifests -->|"defines layout"| node_teams

click node_harness "https://github.com/sting8k/piggery/tree/main/extensions"
click node_piadapter "https://github.com/sting8k/piggery/blob/main/extensions/pi/adapter.mjs"
click node_harnessclients "https://github.com/sting8k/piggery/blob/main/extensions/pi/client.mjs"
click node_paseoplugin "https://github.com/sting8k/piggery/blob/main/extensions/paseo/index.client.tsx"
click node_cli "https://github.com/sting8k/piggery/tree/main/internal/cli"
click node_daemon "https://github.com/sting8k/piggery/blob/main/internal/server/server.go"
click node_protocol "https://github.com/sting8k/piggery/blob/main/internal/proto/proto.go"
click node_engine "https://github.com/sting8k/piggery/blob/main/internal/core/engine.go"
click node_teams "https://github.com/sting8k/piggery/tree/main/internal/core"
click node_mailbox "https://github.com/sting8k/piggery/blob/main/internal/core/mail.go"
click node_workerdriver "https://github.com/sting8k/piggery/blob/main/internal/driver/local/runner.go"
click node_harnessdrivers "https://github.com/sting8k/piggery/tree/main/internal/driver/local"
click node_state "https://github.com/sting8k/piggery/blob/main/internal/store/store.go"
click node_manifests "https://github.com/sting8k/piggery/blob/main/manifests/manifests.go"
click node_top "https://github.com/sting8k/piggery/blob/main/internal/cli/top.go"
click node_topview "https://github.com/sting8k/piggery/blob/main/internal/cli/topview.go"
click node_paseoview "https://github.com/sting8k/piggery/blob/main/extensions/paseo/client/farm.tsx"
click node_paseodata "https://github.com/sting8k/piggery/blob/main/extensions/paseo/shared/view.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_harness,node_piadapter,node_harnessclients,node_paseoplugin,node_paseoview,node_paseodata toneBlue
class node_daemon,node_protocol,node_workerdriver,node_harnessdrivers,node_state toneAmber
class node_engine,node_teams,node_mailbox,node_manifests toneMint
class node_cli,node_top,node_topview toneRose
class node_agent toneIndigo
```

## Components

### Agent integrations

- [Harness plugins](https://github.com/sting8k/piggery/tree/main/extensions): `extensions`
- [Turn adapter](https://github.com/sting8k/piggery/blob/main/extensions/pi/adapter.mjs): `extensions/pi/adapter.mjs`
- [Socket clients](https://github.com/sting8k/piggery/blob/main/extensions/pi/client.mjs): `extensions/pi/client.mjs`
- [Paseo plugin](https://github.com/sting8k/piggery/blob/main/extensions/paseo/index.client.tsx): `extensions/paseo/index.client.tsx`
- [Paseo farm view](https://github.com/sting8k/piggery/blob/main/extensions/paseo/client/farm.tsx): `extensions/paseo/client/farm.tsx`
- [Paseo view model](https://github.com/sting8k/piggery/blob/main/extensions/paseo/shared/view.ts): `extensions/paseo/shared/view.ts`

### Daemon runtime

- [Socket daemon](https://github.com/sting8k/piggery/blob/main/internal/server/server.go): `internal/server/server.go`
- [JSON-line protocol](https://github.com/sting8k/piggery/blob/main/internal/proto/proto.go): `internal/proto/proto.go`
- [Worker runner](https://github.com/sting8k/piggery/blob/main/internal/driver/local/runner.go): `internal/driver/local/runner.go`
- [Harness drivers](https://github.com/sting8k/piggery/tree/main/internal/driver/local): `internal/driver/local`
- [SQLite state](https://github.com/sting8k/piggery/blob/main/internal/store/store.go): `internal/store/store.go`

### Farm domain

- [Farm engine](https://github.com/sting8k/piggery/blob/main/internal/core/engine.go): `internal/core/engine.go`
- [Teams and roles](https://github.com/sting8k/piggery/tree/main/internal/core): `internal/core`
- [Mailbox and events](https://github.com/sting8k/piggery/blob/main/internal/core/mail.go): `internal/core/mail.go`
- [Farm layouts](https://github.com/sting8k/piggery/blob/main/manifests/manifests.go): `manifests/manifests.go`

### Operations and views

- [CLI](https://github.com/sting8k/piggery/tree/main/internal/cli): `internal/cli`
- [Farm monitor](https://github.com/sting8k/piggery/blob/main/internal/cli/top.go): `internal/cli/top.go`
- [Monitor rendering](https://github.com/sting8k/piggery/blob/main/internal/cli/topview.go): `internal/cli/topview.go`

### Other components

- **Coding agent**

## Connections

- Coding agent → Harness plugins: uses harness (evidence: `README.md`)
- Harness plugins → Turn adapter: maps turns (evidence: `extensions/pi/index.ts`)
- Harness plugins → Socket clients: calls daemon (evidence: `extensions/pi/index.ts`)
- Socket clients → Socket daemon: sends requests (evidence: `extensions/pi/client.mjs`)
- Socket daemon → JSON-line protocol: speaks protocol (evidence: `internal/server/server.go`)
- Socket daemon → Farm engine: dispatches calls (evidence: `internal/server/server.go`)
- Socket daemon → SQLite state: uses storage (evidence: `internal/server/server.go`)
- Socket daemon → Worker runner: manages workers (evidence: `internal/server/server.go`)
- Socket daemon → Farm layouts: loads layouts (evidence: `internal/server/server.go`)
- Farm engine → Teams and roles: enforces roles
- Farm engine → Mailbox and events: routes mail
- Worker runner → Harness drivers: selects harness (evidence: `internal/driver/local/runner.go`)
- CLI → Socket daemon: starts daemon
- CLI → Farm engine: queries farm (evidence: `internal/cli/top.go`)
- Farm monitor → Monitor rendering: renders monitor (evidence: `internal/cli/top.go`)
- Paseo plugin → Paseo farm view: registers view (evidence: `extensions/paseo/index.client.tsx`)
- Paseo farm view → Paseo view model: builds display (evidence: `extensions/paseo/client/farm.tsx`)
- Paseo plugin → Socket daemon: reads farm data
- Coding agent → Mailbox and events: exchanges mail (evidence: `README.md`)
- Farm layouts → Teams and roles: defines layout (evidence: `README.md`)