# simonw/showboat architecture

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

- Interactive diagram: https://gitdiagram.com/simonw/showboat
- Repository: https://github.com/simonw/showboat

## Overview

1. Showboat is a single Go CLI that centers everything around one artifact: a Markdown document that is both human-readable documentation and a replayable execution log. The document contains commentary, executable code blocks, captured output blocks, and image references.

2. The command surface lives in `main.go` plus `cmd/`. The subcommands are `init`, `note`, `exec`, `image`, `pop`, `verify`, and `extract`, with a shared `--workdir` option. The CLI is the top-level boundary between the user and all other subsystems.

3. The Markdown document layer is in `markdown/`. It is responsible for parsing an existing showboat document into structured blocks, and writing those blocks back out. This layer is the core data model boundary: all command logic works by transforming document blocks rather than editing raw text ad hoc.

4. `init`, `note`, `exec`, `image`, and `pop` are document mutation commands. They read the current Markdown file, modify the block sequence, and write the file back. `init` creates the initial title/timestamp/id scaffold; `note` appends prose; `exec` appends a code block plus its output; `image` appends an image block and copies the file; `pop` removes the last logical entry, which may span multiple blocks.

5. Execution is isolated in `exec/`. `runner.go` runs shell/interpreter commands in the chosen working directory and captures output, while `image.go` handles image file copy and naming concerns. This subsystem is the main runtime boundary where external processes are invoked and their stdout/stderr become document content.

6. `showboat exec` is special because it has two outputs: it prints the captured output to stdout for the operator, and it also appends that output into the Markdown file. The CLI exit code mirrors the executed command’s exit code, so agents can react immediately to failures while still preserving the failed attempt in the document.

7. `verify` replays the document as an executable spec. It parses the Markdown, re-runs each code block, skips image blocks, and diffs the new output against the recorded output. This creates a validation boundary between stored evidence and actual current behavior, and optionally writes an updated copy when outputs drift.

8. `extract` is the inverse transformation: it parses a finished document and emits the sequence of Showboat CLI commands that could recreate it. It intentionally omits output blocks because those are derived from `exec` runs, making `extract` a provenance/debugging tool for the document history.

9. Remote streaming is an optional side effect controlled by `SHOWBOAT_REMOTE_URL`. When enabled, mutating commands POST their content to a remote receiver, keyed by a UUID stored in the document as an HTML comment. `note`, `exec`, `init`, and `pop` use form-encoded posts; `image` uses multipart upload. This is a separate integration boundary and never blocks the main local command on remote failures.

10. Filesystem behavior matters to the architecture: markdown docs are the primary store, and images are copied into the same directory as the document so the file can remain self-contained. The generated filenames and preserved alt text are part of the document-writing contract.

11. The test layout mirrors the subsystems: unit tests exist for Markdown parsing/writing, execution, image handling, and each CLI command, plus an integration test. That suggests the main architectural risk is consistency between parsing, mutation, replay, and round-tripping.

12. CI/release automation is present in GitHub Actions workflows. The repo is built and tested as a Go tool, and the README also shows a Python wheel publishing path via `go-to-wheel`, which affects distribution but not the runtime architecture.

Main entry points: [`cmd/build.go`](https://github.com/simonw/showboat/blob/main/cmd/build.go) (dispatch), [`markdown/parser.go`](https://github.com/simonw/showboat/blob/main/markdown/parser.go) (parse), [`markdown/writer.go`](https://github.com/simonw/showboat/blob/main/markdown/writer.go) (write), [`cmd/remote.go`](https://github.com/simonw/showboat/blob/main/cmd/remote.go) (remote)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_main["main<br/>entrypoint<br/>[main.go]"]
  node_build["dispatch<br/>cli core<br/>[build.go]"]
  node_init["init<br/>mutate cmd<br/>[init.go]"]
  node_note["note<br/>mutate cmd"]
  node_execcmd["exec<br/>mutate cmd"]
  node_imagecmd["image<br/>mutate cmd"]
  node_pop["pop<br/>mutate cmd<br/>[pop.go]"]
  node_verify["verify<br/>replay cmd<br/>[verify.go]"]
  node_extract["extract<br/>export cmd<br/>[extract.go]"]
end

subgraph group_doc["Document"]
  node_blocks["blocks<br/>doc model<br/>[blocks.go]"]
  node_parser["parse<br/>[parser.go]"]
  node_writer["write<br/>[writer.go]"]
  node_showboatdoc["showboat doc<br/>artifact"]
end

subgraph group_runtime["Runtime"]
  node_runner["runner<br/>exec runtime<br/>[runner.go]"]
  node_image["image<br/>file runtime<br/>[image.go]"]
end

subgraph group_integration["Integration"]
  node_remote["remote<br/>sync cmd<br/>[remote.go]"]
  node_remoteendpoint[("remote receiver<br/>external sink")]
end

node_main -->|"starts"| node_build
node_build -->|"routes"| node_init
node_build -->|"routes"| node_note
node_build -->|"routes"| node_execcmd
node_build -->|"routes"| node_imagecmd
node_build -->|"routes"| node_pop
node_build -->|"routes"| node_verify
node_build -->|"routes"| node_extract
node_init -->|"reads/writes"| node_parser
node_note -->|"reads"| node_parser
node_execcmd -->|"reads"| node_parser
node_imagecmd -->|"reads"| node_parser
node_pop -->|"reads"| node_parser
node_verify -->|"parses"| node_parser
node_extract -->|"parses"| node_parser
node_parser -->|"produces"| node_blocks
node_blocks -->|"serializes"| node_writer
node_init -->|"writes"| node_writer
node_note -->|"writes"| node_writer
node_execcmd -->|"writes"| node_writer
node_imagecmd -->|"writes"| node_writer
node_pop -->|"writes"| node_writer
node_verify -->|"replays"| node_runner
node_execcmd -->|"executes"| node_runner
node_execcmd -->|"appends output"| node_showboatdoc
node_execcmd -->|"streams"| node_remote
node_note -->|"streams"| node_remote
node_init -->|"streams"| node_remote
node_pop -->|"streams"| node_remote
node_imagecmd -->|"copies"| node_image
node_image -->|"references"| node_showboatdoc
node_remote -->|"posts"| node_remoteendpoint
node_verify -->|"compares"| node_showboatdoc
node_extract -->|"reconstructs"| node_showboatdoc

click node_main "https://github.com/simonw/showboat/blob/main/main.go"
click node_build "https://github.com/simonw/showboat/blob/main/cmd/build.go"
click node_init "https://github.com/simonw/showboat/blob/main/cmd/init.go"
click node_pop "https://github.com/simonw/showboat/blob/main/cmd/pop.go"
click node_verify "https://github.com/simonw/showboat/blob/main/cmd/verify.go"
click node_extract "https://github.com/simonw/showboat/blob/main/cmd/extract.go"
click node_remote "https://github.com/simonw/showboat/blob/main/cmd/remote.go"
click node_blocks "https://github.com/simonw/showboat/blob/main/markdown/blocks.go"
click node_parser "https://github.com/simonw/showboat/blob/main/markdown/parser.go"
click node_writer "https://github.com/simonw/showboat/blob/main/markdown/writer.go"
click node_runner "https://github.com/simonw/showboat/blob/main/exec/runner.go"
click node_image "https://github.com/simonw/showboat/blob/main/exec/image.go"

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_main,node_build,node_init,node_note,node_execcmd,node_imagecmd,node_pop,node_verify,node_extract toneBlue
class node_blocks,node_parser,node_writer,node_showboatdoc toneAmber
class node_runner,node_image toneMint
class node_remote,node_remoteendpoint toneRose
```

## Components

### CLI

User-facing command surface and subcommands

- [main](https://github.com/simonw/showboat/blob/main/main.go): entrypoint · Program entry and command wiring · `main.go`
- [dispatch](https://github.com/simonw/showboat/blob/main/cmd/build.go): cli core · Shared CLI setup and subcommand routing · `cmd/build.go`
- [init](https://github.com/simonw/showboat/blob/main/cmd/init.go): mutate cmd · Creates the initial showboat document scaffold · `cmd/init.go`
- **note**: mutate cmd · Appends prose blocks to the document
- **exec**: mutate cmd · Runs a command and appends code plus output
- **image**: mutate cmd · Appends an image block and copies the file
- [pop](https://github.com/simonw/showboat/blob/main/cmd/pop.go): mutate cmd · Removes the last logical document entry · `cmd/pop.go`
- [verify](https://github.com/simonw/showboat/blob/main/cmd/verify.go): replay cmd · Replays code blocks and compares recorded output · `cmd/verify.go`
- [extract](https://github.com/simonw/showboat/blob/main/cmd/extract.go): export cmd · Emits CLI commands that recreate a document · `cmd/extract.go`

### Document

Markdown document model and block transformations

- [blocks](https://github.com/simonw/showboat/blob/main/markdown/blocks.go): doc model · Block types and document structure · `markdown/blocks.go`
- [parse](https://github.com/simonw/showboat/blob/main/markdown/parser.go): markdown parse · Reads showboat Markdown into structured blocks · `markdown/parser.go`
- [write](https://github.com/simonw/showboat/blob/main/markdown/writer.go): markdown write · Renders structured blocks back to Markdown · `markdown/writer.go`
- **showboat doc**: artifact · Markdown log that stores notes, code, output, and images

### Runtime

Execution and image handling

- [runner](https://github.com/simonw/showboat/blob/main/exec/runner.go): exec runtime · Runs shell or interpreter commands in a workdir · `exec/runner.go`
- [image](https://github.com/simonw/showboat/blob/main/exec/image.go): file runtime · Copies images and assigns document-relative names · `exec/image.go`

### Integration

Optional remote streaming and release automation

- [remote](https://github.com/simonw/showboat/blob/main/cmd/remote.go): sync cmd · Optional remote streaming and upload handling · `cmd/remote.go`
- **remote receiver**: external sink · Optional server receiving streamed mutations

## Connections

- main → dispatch: starts · Main delegates CLI setup and command selection
- dispatch → init: routes · Dispatches init subcommand
- dispatch → note: routes · Dispatches note subcommand
- dispatch → exec: routes · Dispatches exec subcommand
- dispatch → image: routes · Dispatches image subcommand
- dispatch → pop: routes · Dispatches pop subcommand
- dispatch → verify: routes · Dispatches verify subcommand
- dispatch → extract: routes · Dispatches extract subcommand
- init → parse: reads/writes · Creates or updates the document through the markdown layer
- note → parse: reads · Loads current blocks before appending prose
- exec → parse: reads · Loads current blocks before adding code/output
- image → parse: reads · Loads current blocks before adding image entry
- pop → parse: reads · Loads current blocks before removing the last entry
- verify → parse: parses · Replays an existing document from structured blocks
- extract → parse: parses · Reads the document structure for command reconstruction
- parse → blocks: produces · Parser converts Markdown into block structures
- blocks → write: serializes · Writer turns blocks back into Markdown text
- init → write: writes · Writes the initial scaffold to disk
- note → write: writes · Persists updated block sequence
- exec → write: writes · Persists code block and captured output
- image → write: writes · Persists image block and alt text
- pop → write: writes · Persists the shortened document
- verify → runner: replays · Re-executes code blocks for comparison
- exec → runner: executes · Runs the requested command in the workdir
- exec → showboat doc: appends output · Captured stdout/stderr becomes stored evidence
- exec → remote: streams · Mutating command can publish content remotely
- note → remote: streams · Optional remote post of appended prose
- init → remote: streams · Optional remote post of new document metadata
- pop → remote: streams · Optional remote post of removal event
- image → image: copies · Copies image into the document directory
- image → showboat doc: references · Image entry is stored alongside the Markdown log
- remote → remote receiver: posts · Sends form or multipart updates when enabled
- verify → showboat doc: compares · Checks recorded output against current behavior
- extract → showboat doc: reconstructs · Derives CLI history from the saved document
