# ski043/marshal-factory architecture

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

- Interactive diagram: https://gitdiagram.com/ski043/marshal-factory
- Repository: https://github.com/ski043/marshal-factory

## Overview

marshal-factory turns Linear issues into pull requests through a human-visible software-agent workflow. Issues arrive from Linear, the panel, or Slack; the runner claims work, launches a T3 Code thread on a branch, and the agent investigates, implements, verifies, and opens a PR. Reporter events flow through the ingest function into Postgres and appear in the live panel. Owners answer questions and review merges; eligible confident PRs may be merged automatically. The README establishes these product relationships; unsampled implementation details are represented at their existing directory paths.

Main entry points: [`runner/index.ts`](https://github.com/ski043/marshal-factory/blob/main/runner/index.ts) (Runner daemon), [`runner/ops.ts`](https://github.com/ski043/marshal-factory/blob/main/runner/ops.ts) (Job operations), [`lib/sources/linear.ts`](https://github.com/ski043/marshal-factory/blob/main/lib/sources/linear.ts) (Source adapters), [`app/(panel)/page.tsx`](https://github.com/ski043/marshal-factory/blob/main/app/(panel)/page.tsx) (Factory panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_panel["Owner panel"]
  node_panel_ui["Factory panel<br/>[page.tsx]"]
  node_panel_queries["Live panel data<br/>[live-queries.ts]"]
  node_panel_actions["Panel actions<br/>[new-job.ts]"]
  node_slack_routes["Slack routes<br/>[route.ts]"]
end

subgraph group_intake["Intake and telemetry"]
  node_source_adapters["Source adapters<br/>[linear.ts]"]
  node_reporter["Reporter hooks<br/>[report.ts]"]
  node_ingest_function["Ingest function<br/>[index.ts]"]
  node_ingest_logic["Event ingestion<br/>[ingest.ts]"]
  node_event_contract["Event contracts<br/>[events.ts]"]
end

subgraph group_runner["Runner workflow"]
  node_runner_daemon["Runner daemon<br/>[index.ts]"]
  node_runner_ops["Job operations<br/>[ops.ts]"]
  node_t3_client["T3 client<br/>[t3-client.ts]"]
  node_harness["Agent harness<br/>[harness.ts]"]
  node_modal_sandbox["Modal sandbox<br/>[sandbox.ts]"]
end

subgraph group_integrations["External integrations"]
  node_github_app["GitHub App<br/>[app.ts]"]
  node_pull_requests["Pull request services<br/>[pulls.ts]"]
end

subgraph group_governance["Review and persistence"]
  node_merge_service["Merge workflow<br/>[merge-service.ts]"]
  node_inbox["Inbox decisions<br/>[inbox.ts]"]
  node_postgres[("Postgres state<br/>[schema.ts]")]
  node_auth["Owner authorization<br/>[server.ts]"]
end

node_owner(("Owner"))
node_linear{{"Linear issues"}}
node_slack{{"Slack"}}

node_linear -->|"provides issues"| node_source_adapters
node_source_adapters -->|"supplies work"| node_runner_daemon
node_owner -->|"files jobs"| node_panel_ui
node_panel_ui -.->|"submits jobs"| node_panel_actions
node_panel_actions -.->|"files jobs"| node_source_adapters
node_slack -->|"submits commands"| node_slack_routes
node_slack_routes -.->|"files jobs"| node_source_adapters
node_reporter -->|"sends events"| node_ingest_function
node_ingest_function -->|"processes events"| node_ingest_logic
node_ingest_logic -->|"writes events"| node_postgres
node_runner_daemon -->|"coordinates work"| node_runner_ops
node_runner_ops -.->|"starts threads"| node_t3_client
node_runner_ops -->|"runs harness"| node_harness
node_harness -.->|"runs optionally"| node_modal_sandbox
node_runner_daemon -->|"posts events"| node_ingest_function
node_runner_daemon -.->|"reads job state"| node_postgres
node_runner_ops -.->|"updates issues"| node_source_adapters
node_runner_ops -->|"opens pull requests"| node_pull_requests
node_pull_requests -->|"uses credentials"| node_github_app
node_github_app -->|"authenticates requests"| node_pull_requests
node_runner_daemon -->|"dispatches merges"| node_merge_service
node_merge_service -.->|"checks and merges"| node_pull_requests
node_owner -->|"answers questions"| node_inbox
node_panel_ui -.->|"loads live data"| node_panel_queries
node_panel_queries -->|"queries state"| node_postgres
node_panel_ui -->|"requires owner"| node_auth
node_ingest_logic -->|"validates events"| node_event_contract

click node_panel_ui "https://github.com/ski043/marshal-factory/blob/main/app/(panel)/page.tsx"
click node_panel_queries "https://github.com/ski043/marshal-factory/blob/main/lib/live-queries.ts"
click node_panel_actions "https://github.com/ski043/marshal-factory/blob/main/app/actions/new-job.ts"
click node_slack_routes "https://github.com/ski043/marshal-factory/blob/main/app/api/slack/commands/route.ts"
click node_source_adapters "https://github.com/ski043/marshal-factory/blob/main/lib/sources/linear.ts"
click node_reporter "https://github.com/ski043/marshal-factory/blob/main/hooks/report.ts"
click node_ingest_function "https://github.com/ski043/marshal-factory/blob/main/functions/ingest/index.ts"
click node_ingest_logic "https://github.com/ski043/marshal-factory/blob/main/lib/ingest.ts"
click node_event_contract "https://github.com/ski043/marshal-factory/blob/main/lib/events.ts"
click node_runner_daemon "https://github.com/ski043/marshal-factory/blob/main/runner/index.ts"
click node_runner_ops "https://github.com/ski043/marshal-factory/blob/main/runner/ops.ts"
click node_t3_client "https://github.com/ski043/marshal-factory/blob/main/lib/t3-client.ts"
click node_harness "https://github.com/ski043/marshal-factory/blob/main/lib/harness.ts"
click node_modal_sandbox "https://github.com/ski043/marshal-factory/blob/main/lib/sandbox.ts"
click node_github_app "https://github.com/ski043/marshal-factory/blob/main/lib/github/app.ts"
click node_pull_requests "https://github.com/ski043/marshal-factory/blob/main/lib/github/pulls.ts"
click node_merge_service "https://github.com/ski043/marshal-factory/blob/main/runner/merge-service.ts"
click node_inbox "https://github.com/ski043/marshal-factory/blob/main/lib/inbox.ts"
click node_postgres "https://github.com/ski043/marshal-factory/blob/main/db/schema.ts"
click node_auth "https://github.com/ski043/marshal-factory/blob/main/lib/auth/server.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_panel_ui,node_panel_queries,node_panel_actions,node_slack_routes toneBlue
class node_source_adapters,node_reporter,node_ingest_function,node_ingest_logic,node_event_contract toneAmber
class node_runner_daemon,node_runner_ops,node_t3_client,node_harness,node_modal_sandbox toneMint
class node_github_app,node_pull_requests toneRose
class node_merge_service,node_inbox,node_postgres,node_auth,node_owner,node_linear,node_slack toneIndigo
```

## Components

### Owner panel

- [Factory panel](https://github.com/ski043/marshal-factory/blob/main/app/(panel)/page.tsx): `app/(panel)/page.tsx`
- [Live panel data](https://github.com/ski043/marshal-factory/blob/main/lib/live-queries.ts): `lib/live-queries.ts`
- [Panel actions](https://github.com/ski043/marshal-factory/blob/main/app/actions/new-job.ts): `app/actions/new-job.ts`
- [Slack routes](https://github.com/ski043/marshal-factory/blob/main/app/api/slack/commands/route.ts): `app/api/slack/commands/route.ts`

### Intake and telemetry

- [Source adapters](https://github.com/ski043/marshal-factory/blob/main/lib/sources/linear.ts): `lib/sources/linear.ts`
- [Reporter hooks](https://github.com/ski043/marshal-factory/blob/main/hooks/report.ts): `hooks/report.ts`
- [Ingest function](https://github.com/ski043/marshal-factory/blob/main/functions/ingest/index.ts): `functions/ingest/index.ts`
- [Event ingestion](https://github.com/ski043/marshal-factory/blob/main/lib/ingest.ts): `lib/ingest.ts`
- [Event contracts](https://github.com/ski043/marshal-factory/blob/main/lib/events.ts): `lib/events.ts`

### Runner workflow

- [Runner daemon](https://github.com/ski043/marshal-factory/blob/main/runner/index.ts): `runner/index.ts`
- [Job operations](https://github.com/ski043/marshal-factory/blob/main/runner/ops.ts): `runner/ops.ts`
- [T3 client](https://github.com/ski043/marshal-factory/blob/main/lib/t3-client.ts): `lib/t3-client.ts`
- [Agent harness](https://github.com/ski043/marshal-factory/blob/main/lib/harness.ts): `lib/harness.ts`
- [Modal sandbox](https://github.com/ski043/marshal-factory/blob/main/lib/sandbox.ts): `lib/sandbox.ts`

### External integrations

- [GitHub App](https://github.com/ski043/marshal-factory/blob/main/lib/github/app.ts): `lib/github/app.ts`
- [Pull request services](https://github.com/ski043/marshal-factory/blob/main/lib/github/pulls.ts): `lib/github/pulls.ts`

### Review and persistence

- [Merge workflow](https://github.com/ski043/marshal-factory/blob/main/runner/merge-service.ts): `runner/merge-service.ts`
- [Inbox decisions](https://github.com/ski043/marshal-factory/blob/main/lib/inbox.ts): `lib/inbox.ts`
- [Postgres state](https://github.com/ski043/marshal-factory/blob/main/db/schema.ts): `db/schema.ts`
- [Owner authorization](https://github.com/ski043/marshal-factory/blob/main/lib/auth/server.ts): `lib/auth/server.ts`

### Other components

- **Owner**
- **Linear issues**
- **Slack**

## Connections

- Linear issues → Source adapters: provides issues (evidence: `README.md`)
- Source adapters → Runner daemon: supplies work (evidence: `README.md`)
- Owner → Factory panel: files jobs (evidence: `README.md`)
- Factory panel → Panel actions: submits jobs
- Panel actions → Source adapters: files jobs
- Slack → Slack routes: submits commands (evidence: `README.md`)
- Slack routes → Source adapters: files jobs
- Reporter hooks → Ingest function: sends events (evidence: `README.md`)
- Ingest function → Event ingestion: processes events (evidence: `functions/ingest/index.ts`)
- Event ingestion → Postgres state: writes events (evidence: `README.md`)
- Runner daemon → Job operations: coordinates work (evidence: `runner/index.ts`)
- Job operations → T3 client: starts threads
- Job operations → Agent harness: runs harness (evidence: `README.md`)
- Agent harness → Modal sandbox: runs optionally (evidence: `README.md`)
- Runner daemon → Ingest function: posts events
- Runner daemon → Postgres state: reads job state (evidence: `runner/index.ts`)
- Job operations → Source adapters: updates issues
- Job operations → Pull request services: opens pull requests (evidence: `README.md`)
- Pull request services → GitHub App: uses credentials (evidence: `lib/github/pulls.ts`)
- GitHub App → Pull request services: authenticates requests (evidence: `lib/github/pulls.ts`)
- Runner daemon → Merge workflow: dispatches merges (evidence: `README.md`)
- Merge workflow → Pull request services: checks and merges (evidence: `runner/merge-service.ts`)
- Owner → Inbox decisions: answers questions (evidence: `README.md`)
- Factory panel → Live panel data: loads live data
- Live panel data → Postgres state: queries state (evidence: `lib/live-queries.ts`)
- Factory panel → Owner authorization: requires owner (evidence: `lib/auth/server.ts`)
- Event ingestion → Event contracts: validates events (evidence: `lib/events.ts`)
