# ShowRunner Architecture

## What This App Is

A workflow capture and grounding system. It records _how work gets done_ and produces structured artifacts that can be documented, shared, and eventually replayed.

```
┌─────────────────────────────────────────────────────────────────┐
│                         ShowRunner                               │
│                                                                  │
│   Capture Workflow  →  Structure Steps  →  Export / Replay      │
│                                                                  │
│   (video + events)     (AI analysis)       (docs, widget, agent) │
└─────────────────────────────────────────────────────────────────┘
```

---

## Three Runtime Components

```
┌──────────────┐     HTTP      ┌──────────────────┐
│   React UI   │◄────────────►│  Python Sidecar  │
│  (Frontend)  │               │   (AI + Export)  │
└──────┬───────┘               └──────────────────┘
       │ IPC                          ▲
       ▼                              │ HTTP
┌──────────────┐                      │
│ Rust Backend │──────────────────────┘
│   (Tauri)    │
└──────────────┘

Optional (web workflows):

┌──────────────────────┐   HTTP   ┌──────────────────┐
│ Chrome Extension MV3 │────────►│  Python Sidecar   │
│   (DOM semantics)    │         │ (/api/events/append)│
└──────────────────────┘         └──────────────────┘
```

| Component                       | Purpose                                                                   | Port |
| ------------------------------- | ------------------------------------------------------------------------- | ---- |
| **Rust backend**                | Window management, screen capture, FFmpeg, session storage                | IPC  |
| **React frontend**              | UI views, timeline editor, hotspot editing                                | -    |
| **Python sidecar**              | Accessibility capture (app-focus/keys/scroll), AI-assisted step detection | 8765 |
| **Chrome extension (optional)** | DOM-level workflow events for browser sessions (`dom_*`)                  | -    |

---

## Three Modules

### 1. Capture

**Record screen, clicks, key metadata, app context, and terminal sessions.**

| File                                      | Purpose                                                |
| ----------------------------------------- | ------------------------------------------------------ |
| `src/views/OverlayView.tsx`               | Floating overlay for screen recording                  |
| `src/views/RecordingView.tsx`             | Terminal recording with embedded terminal              |
| `src-tauri/src/recording.rs`              | Spawns `screencapture`, converts to MP4, audio capture |
| `src-tauri/src/overlay.rs`                | Show/hide overlay window                               |
| `src-tauri/src/click_capture.rs`          | Captures click events during recording                 |
| `python_sidecar/capture/accessibility.py` | Keyboard/modifier capture, frontmost window context    |
| `docs/manifest.json`                      | Optional Chrome extension for DOM semantics            |

**Two recording modes:**

- **Screen recording** → Floating overlay (OverlayView)
- **Terminal recording** → Full window with embedded terminal (RecordingView)

---

### 2. Structure (Editor)

**Play video, edit timeline, add hotspots, detect steps.**

| File                                 | Purpose                                |
| ------------------------------------ | -------------------------------------- |
| `src/views/EditorView.tsx`           | Entry point, wraps Editor components   |
| `src/views/Editor/EditorContext.tsx` | Shared state for all editor components |
| `src/views/Editor/EditorMain.tsx`    | Video player + timeline area           |
| `src/views/Editor/EditorSidebar.tsx` | Steps, hotspots, export controls       |
| `src/views/Editor/useEditorState.ts` | State management hook                  |
| `src/components/Timeline.tsx`        | Timeline scrubber with markers         |
| `src/components/HotspotEditor.tsx`   | Hotspot property panel                 |
| `src/components/HotspotOverlay.tsx`  | Renders hotspots on video              |
| `python_sidecar/ai/analyzer.py`      | AI-powered step detection              |

---

### 3. Library

**List, delete, rename workflow recordings.**

| File                        | Purpose                |
| --------------------------- | ---------------------- |
| `src/views/LibraryView.tsx` | Grid of sessions       |
| `src-tauri/src/session.rs`  | CRUD for session files |

---

## Backend (Rust)

All in `src-tauri/src/`:

| File               | Purpose                                       |
| ------------------ | --------------------------------------------- |
| `main.rs`          | App setup, registers commands, starts sidecar |
| `commands.rs`      | All IPC handlers (frontend calls these)       |
| `recording.rs`     | screencapture + ffmpeg + audio muxing         |
| `session.rs`       | Read/write session folders                    |
| `overlay.rs`       | Overlay window management                     |
| `hotkeys.rs`       | Global Cmd+Shift+R                            |
| `devices.rs`       | List displays/windows                         |
| `tray.rs`          | System tray icon                              |
| `terminal.rs`      | Terminal recording coordination               |
| `sharing.rs`       | Local share server                            |
| `sidecar.rs`       | Python sidecar lifecycle management           |
| `python_bridge.rs` | HTTP client for sidecar API                   |
| `click_capture.rs` | Click event capture during recording          |
| `steps.rs`         | Step/marker management                        |

---

## Frontend (React)

All in `src/`:

```
src/
├── views/
│   ├── LibraryView.tsx      # Session grid
│   ├── EditorView.tsx       # Editor entry point
│   ├── Editor/              # Refactored editor components
│   │   ├── EditorContext.tsx
│   │   ├── EditorMain.tsx
│   │   ├── EditorSidebar.tsx
│   │   └── useEditorState.ts
│   ├── OverlayView.tsx      # Screen recording overlay
│   └── RecordingView.tsx    # Terminal recording
│
├── components/
│   ├── Timeline.tsx
│   ├── VideoPlayer.tsx
│   ├── HotspotEditor.tsx
│   ├── HotspotOverlay.tsx
│   ├── ClickRippleOverlay.tsx
│   ├── WalkthroughPlayer.tsx
│   └── ...
│
├── lib/
│   └── api.ts               # All Tauri command wrappers
│
└── App.tsx                  # Routes + navigation event handling
```

---

## Python Sidecar

All in `python_sidecar/`:

```
python_sidecar/
├── main.py                  # FastAPI app entry point
├── api/
│   ├── analysis.py          # AI analysis endpoints
│   ├── export.py            # Markdown/MP4 export
│   ├── events.py            # Event log endpoints
│   └── terminal.py          # Terminal capture endpoints
├── ai/
│   ├── analyzer.py          # Claude-powered step detection
│   └── prompts.py           # AI prompt templates
├── capture/
│   ├── accessibility.py     # Keyboard/click capture via Quartz
│   ├── events.py            # Event parsing
│   └── filesystem.py        # File watchers
└── export/
    ├── markdown.py          # Markdown documentation generator
    └── screenshots.py       # Frame extraction
```

---

## Data Storage

Sessions saved to: `~/Library/Application Support/dev.showrunner.app/sessions/`

```
{session-id}/
├── metadata.json    # Title, duration, hotspots
├── recording.mp4    # Visual recording (never modified)
├── events.ndjson    # Append-only event log (clicks, keys, markers)
├── steps.json       # Structured workflow steps
├── edits.json       # Non-destructive edit patches
└── terminal.cast    # Terminal recording (optional)
```

**`events.ndjson` is the key artifact** — each line is a timestamped event:

```json
{"type": "app_focus", "ts_ms": 0, "app": "iTerm2", "window": "farman@MacBook-Pro:~"}
{"type": "keypress", "ts_ms": 2456, "key": "<redacted>", "key_type": "alphanumeric", "redacted": true, "modifiers": []}
{"type": "shortcut", "ts_ms": 2670, "key": "<redacted>", "modifiers": ["shift"], "redacted": true}
{"type": "click", "ts_ms": 3122, "x": 41.6, "y": 18.6, "button": "left"}
{"type": "dom_navigation", "ts_ms": 4200, "url": "https://www.bestbuy.com/site/searchpage.jsp?st=iphone", "title": "iphone - Best Buy", "transition": "load"}
{"type": "dom_action", "ts_ms": 4800, "action": "click", "url": "https://mail.google.com/mail/u/0/#inbox", "target": {"role":"link","name":"Re: Interview loop details"}}
{"type": "marker", "ts_ms": 5789, "label": "Manual Step"}
```

This format enables replay, documentation, and eventual automated execution.

Notes:

- Alphanumeric keys are redacted by default for privacy.
- For richer browser workflows, an optional Chrome extension can append `dom_*` semantic events via the sidecar.
- `Auto Steps` is a frontend heuristic pass over loaded timeline markers + clicks (not a backend command).
- Markdown/MP4 export is handled via Tauri commands and surfaced with in-app status + output path.

---

## Two Windows

| Window  | Label               | Purpose                                                  |
| ------- | ------------------- | -------------------------------------------------------- |
| Main    | `main`              | Library, Editor, full Recording view (starts hidden)     |
| Overlay | `recording-overlay` | Floating recording controls (transparent, always-on-top) |

Windows communicate via Tauri events. When emitting from overlay to main, use `emitTo("main", ...)` to target the specific window.

---

## If You Want To...

| Do this...                | Edit this file                                 |
| ------------------------- | ---------------------------------------------- |
| Change recording overlay  | `src/views/OverlayView.tsx`                    |
| Change terminal recording | `src/views/RecordingView.tsx`                  |
| Change recording backend  | `src-tauri/src/recording.rs`                   |
| Add editor features       | `src/views/Editor/*.tsx`                       |
| Add hotspot features      | `src/components/HotspotEditor.tsx`             |
| Change video playback     | `src/components/VideoPlayer.tsx`               |
| Add AI analysis features  | `python_sidecar/ai/analyzer.py`                |
| Add export formats        | `python_sidecar/export/`                       |
| Add new Tauri command     | `src-tauri/src/commands.rs` + `src/lib/api.ts` |
| Change library UI         | `src/views/LibraryView.tsx`                    |

---

## Tech Stack

- **Desktop:** Tauri 2.2 (Rust)
- **Frontend:** React 18, TypeScript, Vite
- **Sidecar:** Python 3.11, FastAPI, Claude API
- **Recording:** macOS `screencapture` + FFmpeg
- **Terminal:** xterm.js + Python PTY
- **Accessibility:** PyObjC (Quartz/AppKit)