# anhsirksai/ghostwatch architecture

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

- Interactive diagram: https://gitdiagram.com/anhsirksai/ghostwatch
- Repository: https://github.com/anhsirksai/ghostwatch

## Overview

GhostWatch lets spectators submit a wish, watch and steer an AI coding agent, and open the app it publishes from a cloud VM. The durable Ghost actor holds séance state and spectator curses; a supervisor starts or resumes the worker, which uses an OpenAI agent and a guarded VM vessel to build and publish the result. The README also documents mock/offline rehearsal. Edges are limited to relationships shown in the excerpts or README; unsampled UI wiring and tool details are not inferred.

Main entry points: [`client/ghost.ts`](https://github.com/anhsirksai/ghostwatch/blob/main/client/ghost.ts) (Haunt worker), [`actor/src/actors.ts`](https://github.com/anhsirksai/ghostwatch/blob/main/actor/src/actors.ts) (Ghost actor), [`client/server.ts`](https://github.com/anhsirksai/ghostwatch/blob/main/client/server.ts) (Bun server), [`client/vm.ts`](https://github.com/anhsirksai/ghostwatch/blob/main/client/vm.ts) (VM vessel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_audience["Séance interface"]
  node_seance_ui["Séance UI<br/>[index.html]"]
  node_app_server["Bun server<br/>[server.ts]"]
end

subgraph group_durable["Durable coordination"]
  node_supervisor["Supervisor<br/>[server.ts]"]
  node_ghost_actor[("Ghost actor<br/>[actors.ts]")]
  node_terse["Terse actor service"]
end

subgraph group_agent["Agent and safety"]
  node_worker["Haunt worker<br/>[ghost.ts]"]
  node_openai["OpenAI"]
  node_exorcist["Exorcist checks<br/>[exorcist.ts]"]
end

subgraph group_runtime["VM and publishing"]
  node_vessel["VM vessel<br/>[vm.ts]"]
  node_freestyle["Freestyle VM"]
  node_mock_vessel["Mock vessel<br/>[vm.ts]"]
  node_published_app["Published app"]
end

node_spectators(("Spectators"))
node_portal_viewers(("Portal visitors"))

node_spectators -->|"use"| node_seance_ui
node_seance_ui -->|"request page"| node_app_server
node_spectators -->|"wish and curse"| node_ghost_actor
node_ghost_actor -->|"sync séance"| node_spectators
node_app_server -->|"prepare socket URL"| node_terse
node_supervisor -->|"read actor state"| node_terse
node_supervisor -->|"start or resume"| node_worker
node_worker -->|"read and update state"| node_ghost_actor
node_ghost_actor -->|"screen curses"| node_exorcist
node_worker -->|"screen actions"| node_exorcist
node_worker -->|"request tool calls"| node_openai
node_worker -->|"execute build tools"| node_vessel
node_vessel -->|"exec, write, publish"| node_freestyle
node_vessel -->|"use without key"| node_mock_vessel
node_worker -->|"store preview URL"| node_ghost_actor
node_portal_viewers -->|"open public URL"| node_published_app
node_app_server -->|"serve mock portal"| node_mock_vessel

click node_seance_ui "https://github.com/anhsirksai/ghostwatch/blob/main/client/public/index.html"
click node_app_server "https://github.com/anhsirksai/ghostwatch/blob/main/client/server.ts"
click node_supervisor "https://github.com/anhsirksai/ghostwatch/blob/main/client/server.ts"
click node_ghost_actor "https://github.com/anhsirksai/ghostwatch/blob/main/actor/src/actors.ts"
click node_worker "https://github.com/anhsirksai/ghostwatch/blob/main/client/ghost.ts"
click node_exorcist "https://github.com/anhsirksai/ghostwatch/blob/main/actor/src/exorcist.ts"
click node_vessel "https://github.com/anhsirksai/ghostwatch/blob/main/client/vm.ts"
click node_mock_vessel "https://github.com/anhsirksai/ghostwatch/blob/main/client/vm.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_seance_ui,node_app_server toneBlue
class node_supervisor,node_ghost_actor,node_terse toneAmber
class node_worker,node_openai,node_exorcist toneMint
class node_vessel,node_freestyle,node_mock_vessel,node_published_app toneRose
class node_spectators,node_portal_viewers toneIndigo
```

## Components

### Séance interface

- [Séance UI](https://github.com/anhsirksai/ghostwatch/blob/main/client/public/index.html): `client/public/index.html`
- [Bun server](https://github.com/anhsirksai/ghostwatch/blob/main/client/server.ts): `client/server.ts`

### Durable coordination

- [Supervisor](https://github.com/anhsirksai/ghostwatch/blob/main/client/server.ts): `client/server.ts`
- [Ghost actor](https://github.com/anhsirksai/ghostwatch/blob/main/actor/src/actors.ts): `actor/src/actors.ts`
- **Terse actor service**

### Agent and safety

- [Haunt worker](https://github.com/anhsirksai/ghostwatch/blob/main/client/ghost.ts): `client/ghost.ts`
- **OpenAI**
- [Exorcist checks](https://github.com/anhsirksai/ghostwatch/blob/main/actor/src/exorcist.ts): `actor/src/exorcist.ts`

### VM and publishing

- [VM vessel](https://github.com/anhsirksai/ghostwatch/blob/main/client/vm.ts): `client/vm.ts`
- **Freestyle VM**
- [Mock vessel](https://github.com/anhsirksai/ghostwatch/blob/main/client/vm.ts): `client/vm.ts`
- **Published app**

### Other components

- **Spectators**
- **Portal visitors**

## Connections

- Spectators → Séance UI: use (evidence: `README.md`)
- Séance UI → Bun server: request page (evidence: `README.md`)
- Spectators → Ghost actor: wish and curse (evidence: `README.md`)
- Ghost actor → Spectators: sync séance (evidence: `README.md`)
- Bun server → Terse actor service: prepare socket URL (evidence: `client/server.ts`)
- Supervisor → Terse actor service: read actor state (evidence: `client/server.ts`)
- Supervisor → Haunt worker: start or resume (evidence: `client/server.ts`)
- Haunt worker → Ghost actor: read and update state (evidence: `client/ghost.ts`)
- Ghost actor → Exorcist checks: screen curses (evidence: `actor/src/actors.ts`)
- Haunt worker → Exorcist checks: screen actions (evidence: `client/ghost.ts`)
- Haunt worker → OpenAI: request tool calls (evidence: `client/ghost.ts`)
- Haunt worker → VM vessel: execute build tools (evidence: `client/ghost.ts`)
- VM vessel → Freestyle VM: exec, write, publish (evidence: `client/vm.ts`)
- VM vessel → Mock vessel: use without key (evidence: `client/vm.ts`)
- Haunt worker → Ghost actor: store preview URL (evidence: `client/ghost.ts`)
- Portal visitors → Published app: open public URL (evidence: `README.md`)
- Bun server → Mock vessel: serve mock portal (evidence: `client/server.ts`)
