# arshadnyx/rollcut architecture

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

- Interactive diagram: https://gitdiagram.com/arshadnyx/rollcut
- Repository: https://github.com/arshadnyx/rollcut
- Video tour (about a minute): https://gitdiagram.com/arshadnyx/rollcut/video

## Overview

Rollcut turns a YAML walkthrough into a narrated browser recording and release assets. The main runtime loads and validates the spec, synthesizes narration before recording, drives a headless browser, then assembles MP4, GIF, and subtitle outputs. Separate authoring tools plan, capture, narrate, repair, and verify walkthroughs; release integration can attach assets and update a README. The tree and README document these capabilities, but several subsystem implementations were not sampled, so their internal wiring is shown only where documented.

Main entry points: [`src/cli.ts`](https://github.com/arshadnyx/rollcut/blob/main/src/cli.ts) (Rollcut CLI), [`src/pipeline.ts`](https://github.com/arshadnyx/rollcut/blob/main/src/pipeline.ts) (Pipeline orchestrator), [`src/media/assemble.ts`](https://github.com/arshadnyx/rollcut/blob/main/src/media/assemble.ts) (Media assembler), [`src/plan/planner.ts`](https://github.com/arshadnyx/rollcut/blob/main/src/plan/planner.ts) (Plan generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Walkthrough authoring"]
  node_planner["Plan generator<br/>[planner.ts]"]
  node_observer["Site observer<br/>[observe.ts]"]
  node_capture["Spec capture<br/>[capture.ts]"]
  node_narrate["Plan narration<br/>[narrate.ts]"]
  node_repair["Spec repair<br/>[repair.ts]"]
  node_matcher["Selector matching<br/>[match.ts]"]
  node_verifier["Plan verifier<br/>[verify.ts]"]
end

subgraph group_recording["Recording runtime"]
  node_spec["Walkthrough spec<br/>[schema.ts]"]
  node_spec_loader["Spec loader<br/>[load.ts]"]
  node_pipeline["Pipeline orchestrator<br/>[pipeline.ts]"]
  node_recorder["Browser recorder<br/>[driver.ts]"]
  node_step_driver["Step driver<br/>[steps.ts]"]
  node_tts_planner["Narration timing<br/>[provider.ts]"]
  node_kokoro["Kokoro TTS<br/>[kokoro.ts]"]
  node_edge_tts["Edge TTS<br/>[edge.ts]"]
end

subgraph group_media["Media production"]
  node_raw_video["Raw recording"]
  node_assembler["Media assembler<br/>[assemble.ts]"]
  node_subtitles["Subtitle formatting<br/>[subtitles.ts]"]
  node_zoom["Click zoom<br/>[zoom.ts]"]
  node_assets["MP4 GIF SRT"]
end

subgraph group_release["Release publishing"]
  node_release_publisher["Release publisher<br/>[release.ts]"]
  node_readme_updater["README updater<br/>[readme.ts]"]
end

node_user(("Repository user"))
node_release_event(("Release event"))
node_app(("Target web app"))
node_cli["Rollcut CLI<br/>[cli.ts]"]
node_action["GitHub Action<br/>[action.ts]"]
node_github(("GitHub Releases API"))

node_user -->|"runs command"| node_cli
node_release_event -->|"triggers"| node_action
node_action -->|"runs pipeline"| node_pipeline
node_action -->|"publishes assets"| node_release_publisher
node_cli -->|"runs pipeline"| node_pipeline
node_cli -->|"generates plan"| node_planner
node_cli -->|"captures steps"| node_capture
node_cli -->|"annotates plan"| node_narrate
node_cli -->|"repairs spec"| node_repair
node_pipeline -->|"loads spec"| node_spec_loader
node_spec_loader -->|"validates into"| node_spec
node_pipeline -->|"plans narration"| node_tts_planner
node_tts_planner -->|"synthesizes with"| node_kokoro
node_tts_planner -.->|"synthesizes with"| node_edge_tts
node_pipeline -->|"records walkthrough"| node_recorder
node_recorder -->|"executes steps"| node_step_driver
node_step_driver -->|"drives browser"| node_app
node_recorder -->|"writes recording"| node_raw_video
node_pipeline -->|"assembles media"| node_assembler
node_assembler -->|"reads recording"| node_raw_video
node_assembler -->|"formats captions"| node_subtitles
node_assembler -->|"builds zoom filter"| node_zoom
node_assembler -->|"writes outputs"| node_assets
node_planner -->|"observes site"| node_observer
node_observer -->|"inspects pages"| node_app
node_planner -->|"verifies plan"| node_verifier
node_repair -->|"matches replacements"| node_matcher
node_repair -->|"inspects failed step"| node_observer
node_release_publisher -->|"uploads assets"| node_github
node_release_publisher -->|"updates README"| node_readme_updater
node_readme_updater -->|"commits README"| node_github

click node_cli "https://github.com/arshadnyx/rollcut/blob/main/src/cli.ts"
click node_action "https://github.com/arshadnyx/rollcut/blob/main/src/action.ts"
click node_spec "https://github.com/arshadnyx/rollcut/blob/main/src/spec/schema.ts"
click node_spec_loader "https://github.com/arshadnyx/rollcut/blob/main/src/spec/load.ts"
click node_pipeline "https://github.com/arshadnyx/rollcut/blob/main/src/pipeline.ts"
click node_recorder "https://github.com/arshadnyx/rollcut/blob/main/src/record/driver.ts"
click node_step_driver "https://github.com/arshadnyx/rollcut/blob/main/src/record/steps.ts"
click node_tts_planner "https://github.com/arshadnyx/rollcut/blob/main/src/tts/provider.ts"
click node_kokoro "https://github.com/arshadnyx/rollcut/blob/main/src/tts/kokoro.ts"
click node_edge_tts "https://github.com/arshadnyx/rollcut/blob/main/src/tts/edge.ts"
click node_assembler "https://github.com/arshadnyx/rollcut/blob/main/src/media/assemble.ts"
click node_subtitles "https://github.com/arshadnyx/rollcut/blob/main/src/media/subtitles.ts"
click node_zoom "https://github.com/arshadnyx/rollcut/blob/main/src/media/zoom.ts"
click node_planner "https://github.com/arshadnyx/rollcut/blob/main/src/plan/planner.ts"
click node_observer "https://github.com/arshadnyx/rollcut/blob/main/src/plan/observe.ts"
click node_capture "https://github.com/arshadnyx/rollcut/blob/main/src/plan/capture.ts"
click node_narrate "https://github.com/arshadnyx/rollcut/blob/main/src/plan/narrate.ts"
click node_repair "https://github.com/arshadnyx/rollcut/blob/main/src/plan/repair.ts"
click node_matcher "https://github.com/arshadnyx/rollcut/blob/main/src/plan/match.ts"
click node_verifier "https://github.com/arshadnyx/rollcut/blob/main/src/plan/verify.ts"
click node_release_publisher "https://github.com/arshadnyx/rollcut/blob/main/src/publish/release.ts"
click node_readme_updater "https://github.com/arshadnyx/rollcut/blob/main/src/publish/readme.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_planner,node_observer,node_capture,node_narrate,node_repair,node_matcher,node_verifier,node_user toneBlue
class node_spec,node_spec_loader,node_pipeline,node_recorder,node_step_driver,node_tts_planner,node_kokoro,node_edge_tts toneAmber
class node_raw_video,node_assembler,node_subtitles,node_zoom,node_assets,node_github toneMint
class node_release_publisher,node_readme_updater toneRose
class node_release_event,node_app toneIndigo
class node_cli,node_action toneTeal
```

## Components

### Walkthrough authoring

- [Plan generator](https://github.com/arshadnyx/rollcut/blob/main/src/plan/planner.ts): `src/plan/planner.ts`
- [Site observer](https://github.com/arshadnyx/rollcut/blob/main/src/plan/observe.ts): `src/plan/observe.ts`
- [Spec capture](https://github.com/arshadnyx/rollcut/blob/main/src/plan/capture.ts): `src/plan/capture.ts`
- [Plan narration](https://github.com/arshadnyx/rollcut/blob/main/src/plan/narrate.ts): `src/plan/narrate.ts`
- [Spec repair](https://github.com/arshadnyx/rollcut/blob/main/src/plan/repair.ts): `src/plan/repair.ts`
- [Selector matching](https://github.com/arshadnyx/rollcut/blob/main/src/plan/match.ts): `src/plan/match.ts`
- [Plan verifier](https://github.com/arshadnyx/rollcut/blob/main/src/plan/verify.ts): `src/plan/verify.ts`

### Recording runtime

- [Walkthrough spec](https://github.com/arshadnyx/rollcut/blob/main/src/spec/schema.ts): `src/spec/schema.ts`
- [Spec loader](https://github.com/arshadnyx/rollcut/blob/main/src/spec/load.ts): `src/spec/load.ts`
- [Pipeline orchestrator](https://github.com/arshadnyx/rollcut/blob/main/src/pipeline.ts): `src/pipeline.ts`
- [Browser recorder](https://github.com/arshadnyx/rollcut/blob/main/src/record/driver.ts): `src/record/driver.ts`
- [Step driver](https://github.com/arshadnyx/rollcut/blob/main/src/record/steps.ts): `src/record/steps.ts`
- [Narration timing](https://github.com/arshadnyx/rollcut/blob/main/src/tts/provider.ts): `src/tts/provider.ts`
- [Kokoro TTS](https://github.com/arshadnyx/rollcut/blob/main/src/tts/kokoro.ts): `src/tts/kokoro.ts`
- [Edge TTS](https://github.com/arshadnyx/rollcut/blob/main/src/tts/edge.ts): `src/tts/edge.ts`

### Media production

- **Raw recording**
- [Media assembler](https://github.com/arshadnyx/rollcut/blob/main/src/media/assemble.ts): `src/media/assemble.ts`
- [Subtitle formatting](https://github.com/arshadnyx/rollcut/blob/main/src/media/subtitles.ts): `src/media/subtitles.ts`
- [Click zoom](https://github.com/arshadnyx/rollcut/blob/main/src/media/zoom.ts): `src/media/zoom.ts`
- **MP4 GIF SRT**

### Release publishing

- [Release publisher](https://github.com/arshadnyx/rollcut/blob/main/src/publish/release.ts): `src/publish/release.ts`
- [README updater](https://github.com/arshadnyx/rollcut/blob/main/src/publish/readme.ts): `src/publish/readme.ts`

### Other components

- **Repository user**
- **Release event**
- **Target web app**
- [Rollcut CLI](https://github.com/arshadnyx/rollcut/blob/main/src/cli.ts): `src/cli.ts`
- [GitHub Action](https://github.com/arshadnyx/rollcut/blob/main/src/action.ts): `src/action.ts`
- **GitHub Releases API**

## Connections

- Repository user → Rollcut CLI: runs command
- Release event → GitHub Action: triggers
- GitHub Action → Pipeline orchestrator: runs pipeline
- GitHub Action → Release publisher: publishes assets
- Rollcut CLI → Pipeline orchestrator: runs pipeline
- Rollcut CLI → Plan generator: generates plan
- Rollcut CLI → Spec capture: captures steps
- Rollcut CLI → Plan narration: annotates plan
- Rollcut CLI → Spec repair: repairs spec
- Pipeline orchestrator → Spec loader: loads spec
- Spec loader → Walkthrough spec: validates into
- Pipeline orchestrator → Narration timing: plans narration
- Narration timing → Kokoro TTS: synthesizes with
- Narration timing → Edge TTS: synthesizes with
- Pipeline orchestrator → Browser recorder: records walkthrough
- Browser recorder → Step driver: executes steps
- Step driver → Target web app: drives browser
- Browser recorder → Raw recording: writes recording
- Pipeline orchestrator → Media assembler: assembles media
- Media assembler → Raw recording: reads recording
- Media assembler → Subtitle formatting: formats captions
- Media assembler → Click zoom: builds zoom filter
- Media assembler → MP4 GIF SRT: writes outputs
- Plan generator → Site observer: observes site
- Site observer → Target web app: inspects pages
- Plan generator → Plan verifier: verifies plan
- Spec repair → Selector matching: matches replacements
- Spec repair → Site observer: inspects failed step
- Release publisher → GitHub Releases API: uploads assets
- Release publisher → README updater: updates README
- README updater → GitHub Releases API: commits README