# steipete/summarize architecture

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

- Interactive diagram: https://gitdiagram.com/steipete/summarize
- Repository: https://github.com/steipete/summarize

## Overview

1. **Repository shape**
   This is a TypeScript monorepo with three main deliverables: a **terminal CLI** (`src/`), a **browser extension** (`apps/chrome-extension/`), and a **shared core library** (`packages/core/`). The root also contains docs, tests, release tooling, and CI workflows. `pnpm` workspaces and Vitest are the primary build/test tooling.

2. **Top-level architecture**
   The project is organized around a single product idea: **extract content from URLs/files/media, optionally transcribe or render slides, then summarize with an LLM**. The CLI can run standalone, while the extension delegates heavy work to a local daemon. Shared logic is reused across both surfaces rather than duplicated.

3. **CLI execution path**
   The CLI entrypoint (`src/cli-main.ts`, `src/cli.ts`) feeds into the `src/run/` orchestration layer. That layer resolves input type, applies config and flags, runs extraction/transcription, builds prompts, selects a model/provider, and emits either streamed Markdown, text, or JSON diagnostics. It also owns progress reporting, terminal formatting, retries, and finish-line/cost/metrics output.

4. **Daemon as browser-extension backend**
   The daemon (`src/daemon/`) is the bridge between the extension and the local machine. It exposes HTTP/SSE endpoints, session/state routes, summarize routes, and admin/status routes. The extension talks to `127.0.0.1` with token-based auth; the daemon then executes the same core summarization and media pipelines used by the CLI. It is designed to autostart via platform-specific service managers.

5. **Browser extension structure**
   `apps/chrome-extension/` is a multi-entry extension with a **Side Panel / Firefox Sidebar**, an **options page**, background scripts, and content scripts. The side panel provides chat, navigation, summary rendering, and slides UI. The background layer mediates between panel state, page content, and the daemon. Content scripts handle page extraction/hover/automation tasks inside the active tab.

6. **Extension UX subsystems**
   The side panel is not just a thin viewer: it has its own chat session state, streaming controllers, history storage, slide rendering, summary rendering, navigation handling, and UI settings. There is also a dedicated options page for daemon status, skill/model configuration, logging, and persistence. The panel and options page communicate through shared contracts and runtime message bridges.

7. **Content extraction subsystem**
   The core content pipeline lives in `packages/core/src/content/` and `src/content/`. It covers link previews, readable-HTML extraction, JSON-LD parsing, Firecrawl fallback, URL normalization, and specialized handling for YouTube, podcasts, and generic media pages. This layer is responsible for producing a clean textual representation before any LLM work happens.

8. **Media and transcript pipeline**
   Media handling is a major subsystem, not an edge case. For YouTube, podcasts, audio, and video, the system prefers existing transcripts, then falls back to local or remote transcription providers. The project also has a slide-extraction flow (`src/slides/` and `src/run/flows/url/slides-*`) that uses scene detection, frame extraction, OCR, and timestamped slide cards. External tools like `ffmpeg`, `yt-dlp`, `tesseract`, and whisper/transcription providers materially shape this pipeline.

9. **LLM/provider layer**
   `src/llm/` and parts of `packages/core/src/transcription/` abstract model selection and provider-specific behavior. The repo supports OpenAI-compatible providers plus Anthropic, Google, OpenRouter, NVIDIA, Z.AI, and several CLI backends like Claude/Gemini/Codex/Agent. There is built-in model auto-selection, capability checks, streaming support, prompt formatting, and provider-specific limits/compatibility handling.

10. **Configuration and state boundaries**
   Configuration is layered: CLI flags override `SUMMARIZE_*` env vars, which override `~/.summarize/config.json`, with defaults as fallback. State is split by concern: summary cache, media cache, transcript cache, slide outputs, daemon/session state, and extension persistence. This separation matters because the same input may be processed through different caches depending on whether it came from the CLI, daemon, or extension.

11. **Shared contracts**
   The repo uses explicit contract modules to keep the CLI, daemon, and extension in sync: shared SSE events, runtime/panel payloads, status objects, token/metrics types, and slides text contracts. These contracts are important architecture boundaries because they define what can cross process and transport lines safely.

12. **Infrastructure and delivery**
   The project ships via npm/Homebrew and also supports an installable browser extension. The daemon can register itself with launchd/systemd/Scheduled Tasks, and the repo includes GitHub Actions for CI and GitHub Pages for docs. The documentation site is part of the architecture because it explains operational flows like daemon install, media requirements, and Firefox compatibility.

Main entry points: [`src/run`](https://github.com/steipete/summarize/tree/main/src/run) (Run engine), [`apps/chrome-extension/src/entrypoints/sidepanel`](https://github.com/steipete/summarize/tree/main/apps/chrome-extension/src/entrypoints/sidepanel) (Side panel), [`packages/core/src/content`](https://github.com/steipete/summarize/tree/main/packages/core/src/content) (Content extraction), [`packages/core/src/content/transcript`](https://github.com/steipete/summarize/tree/main/packages/core/src/content/transcript) (Transcript engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI & Daemon"]
  node_node_cli_entry["CLI entrypoint<br/>ts entrypoint<br/>[cli-main.ts]"]
  node_node_run_orchestration["Run engine<br/>orchestrator"]
  node_node_flow_url["URL flow<br/>pipeline"]
  node_node_flow_asset["Asset flow<br/>pipeline"]
  node_node_slides_pipeline["Slides pipeline<br/>media pipeline"]
  node_node_daemon_server["Daemon server<br/>http+sse backend<br/>[server.ts]"]
  node_node_daemon_runtime["Daemon runtime<br/>service runtime"]
  node_node_llm_layer["LLM layer<br/>provider facade"]
end

subgraph group_group_extension["Browser Extension"]
  node_node_ext_sidepanel["Side panel<br/>extension UI"]
  node_node_ext_background["Background bridge<br/>extension runtime"]
  node_node_ext_options["Options page<br/>extension settings"]
  node_node_ext_content["Content scripts<br/>page automation"]
  node_node_ext_lib["Extension contracts<br/>shared ext lib"]
end

subgraph group_group_core["Shared Core"]
  node_node_core_content["Content extraction<br/>core pipeline"]
  node_node_core_transcript["Transcript engine<br/>core pipeline"]
  node_node_core_transcription["Transcription providers<br/>provider adapters"]
  node_node_core_prompts["Prompt kit<br/>prompt templates"]
  node_node_core_contracts["Shared contracts<br/>types boundary<br/>[contracts.ts]"]
end

subgraph group_group_infra["Delivery & Ops"]
  node_node_ops_docs["Docs site<br/>documentation"]
  node_node_ops_ci["CI & release<br/>tooling<br/>[ci.yml]"]
end

node_node_cli_entry -->|"starts"| node_node_run_orchestration
node_node_run_orchestration -->|"extracts"| node_node_core_content
node_node_run_orchestration -->|"loads transcripts"| node_node_core_transcript
node_node_run_orchestration -->|"builds prompts"| node_node_core_prompts
node_node_run_orchestration -->|"generates"| node_node_llm_layer
node_node_run_orchestration -->|"renders slides"| node_node_slides_pipeline
node_node_run_orchestration -->|"routes url"| node_node_flow_url
node_node_run_orchestration -->|"routes asset"| node_node_flow_asset
node_node_daemon_server -->|"serves"| node_node_daemon_runtime
node_node_daemon_runtime -->|"reuses"| node_node_core_content
node_node_daemon_runtime -->|"reuses"| node_node_core_transcript
node_node_daemon_runtime -->|"summarizes"| node_node_llm_layer
node_node_ext_sidepanel -->|"messages"| node_node_ext_background
node_node_ext_background -->|"calls localhost"| node_node_daemon_server
node_node_ext_background -->|"coordinates tab"| node_node_ext_content
node_node_ext_sidepanel -->|"shares contracts"| node_node_ext_lib
node_node_ext_options -->|"shares contracts"| node_node_ext_lib
node_node_ext_content -->|"extracts pages"| node_node_core_content
node_node_core_content -->|"prefers transcripts"| node_node_core_transcript
node_node_core_transcript -->|"falls back"| node_node_core_transcription
node_node_core_content -->|"serializes"| node_node_core_contracts
node_node_core_transcript -->|"serializes"| node_node_core_contracts
node_node_ext_sidepanel -->|"consumes"| node_node_core_contracts
node_node_ops_docs -->|"documents"| node_node_cli_entry
node_node_ops_docs -->|"documents"| node_node_ext_sidepanel
node_node_ops_ci -->|"builds"| node_node_cli_entry
node_node_ops_ci -->|"builds"| node_node_ext_sidepanel

click node_node_cli_entry "https://github.com/steipete/summarize/blob/main/src/cli-main.ts"
click node_node_run_orchestration "https://github.com/steipete/summarize/tree/main/src/run"
click node_node_flow_url "https://github.com/steipete/summarize/tree/main/src/run/flows/url"
click node_node_flow_asset "https://github.com/steipete/summarize/tree/main/src/run/flows/asset"
click node_node_slides_pipeline "https://github.com/steipete/summarize/tree/main/src/slides"
click node_node_daemon_server "https://github.com/steipete/summarize/blob/main/src/daemon/server.ts"
click node_node_daemon_runtime "https://github.com/steipete/summarize/tree/main/src/daemon"
click node_node_llm_layer "https://github.com/steipete/summarize/tree/main/src/llm"
click node_node_ext_sidepanel "https://github.com/steipete/summarize/tree/main/apps/chrome-extension/src/entrypoints/sidepanel"
click node_node_ext_background "https://github.com/steipete/summarize/tree/main/apps/chrome-extension/src/entrypoints/background"
click node_node_ext_options "https://github.com/steipete/summarize/tree/main/apps/chrome-extension/src/entrypoints/options"
click node_node_ext_content "https://github.com/steipete/summarize/tree/main/apps/chrome-extension/src/entrypoints"
click node_node_ext_lib "https://github.com/steipete/summarize/tree/main/apps/chrome-extension/src/lib"
click node_node_core_content "https://github.com/steipete/summarize/tree/main/packages/core/src/content"
click node_node_core_transcript "https://github.com/steipete/summarize/tree/main/packages/core/src/content/transcript"
click node_node_core_transcription "https://github.com/steipete/summarize/tree/main/packages/core/src/transcription"
click node_node_core_prompts "https://github.com/steipete/summarize/tree/main/packages/core/src/prompts"
click node_node_core_contracts "https://github.com/steipete/summarize/blob/main/packages/core/src/shared/contracts.ts"
click node_node_ops_docs "https://github.com/steipete/summarize/tree/main/docs"
click node_node_ops_ci "https://github.com/steipete/summarize/blob/main/.github/workflows/ci.yml"

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_node_cli_entry,node_node_run_orchestration,node_node_flow_url,node_node_flow_asset,node_node_slides_pipeline,node_node_daemon_server,node_node_daemon_runtime,node_node_llm_layer toneBlue
class node_node_ext_sidepanel,node_node_ext_background,node_node_ext_options,node_node_ext_content,node_node_ext_lib toneAmber
class node_node_core_content,node_node_core_transcript,node_node_core_transcription,node_node_core_prompts,node_node_core_contracts toneMint
class node_node_ops_docs,node_node_ops_ci toneRose
```

## Components

### CLI & Daemon

Terminal entrypoint, orchestration, and local backend service.

- [CLI entrypoint](https://github.com/steipete/summarize/blob/main/src/cli-main.ts): ts entrypoint · Main terminal entrypoints that parse flags and hand off to the runner. · `src/cli-main.ts`
- [Run engine](https://github.com/steipete/summarize/tree/main/src/run): orchestrator · Coordinates input resolution, extraction, prompting, model selection, streaming, and finish-line output. · `src/run`
- [URL flow](https://github.com/steipete/summarize/tree/main/src/run/flows/url): pipeline · URL-centric extraction and summary flow, including markdown, timestamps, JSON, and slide variants. · `src/run/flows/url`
- [Asset flow](https://github.com/steipete/summarize/tree/main/src/run/flows/asset): pipeline · File and media ingestion flow for local assets and cached summaries. · `src/run/flows/asset`
- [Slides pipeline](https://github.com/steipete/summarize/tree/main/src/slides): media pipeline · Scene detection, frame extraction, OCR, and slide output rendering. · `src/slides`
- [Daemon server](https://github.com/steipete/summarize/blob/main/src/daemon/server.ts): http+sse backend · Local HTTP/SSE backend with session, summarize, admin, and agent routes for the extension. · `src/daemon/server.ts`
- [Daemon runtime](https://github.com/steipete/summarize/tree/main/src/daemon): service runtime · Daemon request handling, model wiring, progress tracking, autostart integration, and state management. · `src/daemon`
- [LLM layer](https://github.com/steipete/summarize/tree/main/src/llm): provider facade · Model/provider selection, streaming generation, prompt formatting, and provider-specific behavior. · `src/llm`

### Browser Extension

Side panel, options page, background bridge, and content scripts.

- [Side panel](https://github.com/steipete/summarize/tree/main/apps/chrome-extension/src/entrypoints/sidepanel): extension UI · Chat, summary, navigation, slides, and streaming UI for the browser extension. · `apps/chrome-extension/src/entrypoints/sidepanel`
- [Background bridge](https://github.com/steipete/summarize/tree/main/apps/chrome-extension/src/entrypoints/background): extension runtime · Mediates panel state, tab content, daemon access, and runtime message flows. · `apps/chrome-extension/src/entrypoints/background`
- [Options page](https://github.com/steipete/summarize/tree/main/apps/chrome-extension/src/entrypoints/options): extension settings · Daemon status, model and skill configuration, logging, and persistence controls. · `apps/chrome-extension/src/entrypoints/options`
- [Content scripts](https://github.com/steipete/summarize/tree/main/apps/chrome-extension/src/entrypoints): page automation · Extraction, hover, and automation scripts running in the active tab. · `apps/chrome-extension/src/entrypoints`
- [Extension contracts](https://github.com/steipete/summarize/tree/main/apps/chrome-extension/src/lib): shared ext lib · Shared payloads, SSE, token, metrics, settings, and daemon-status utilities. · `apps/chrome-extension/src/lib`

### Shared Core

Reusable content extraction, transcript, prompt, and contract logic.

- [Content extraction](https://github.com/steipete/summarize/tree/main/packages/core/src/content): core pipeline · Shared URL normalization, link previews, readable HTML, JSON-LD, and media-aware extraction. · `packages/core/src/content`
- [Transcript engine](https://github.com/steipete/summarize/tree/main/packages/core/src/content/transcript): core pipeline · Transcript detection, normalization, parsing, caching, and provider flows for YouTube and podcasts. · `packages/core/src/content/transcript`
- [Transcription providers](https://github.com/steipete/summarize/tree/main/packages/core/src/transcription): provider adapters · Whisper and remote transcription backends, chunking, ffmpeg integration, and provider setup. · `packages/core/src/transcription`
- [Prompt kit](https://github.com/steipete/summarize/tree/main/packages/core/src/prompts): prompt templates · Shared prompt builders and summary-length/system templates. · `packages/core/src/prompts`
- [Shared contracts](https://github.com/steipete/summarize/blob/main/packages/core/src/shared/contracts.ts): types boundary · Cross-runtime event, stream, slides, status, and payload contracts. · `packages/core/src/shared/contracts.ts`

### Delivery & Ops

Docs, CI, packaging, release, and workspace tooling.

- [Docs site](https://github.com/steipete/summarize/tree/main/docs): documentation · Operational docs for CLI, extension, media, config, daemon install, and release flows. · `docs`
- [CI & release](https://github.com/steipete/summarize/blob/main/.github/workflows/ci.yml): tooling · GitHub Actions, packaging scripts, release helpers, and workspace configuration. · `.github/workflows/ci.yml`

## Connections

- CLI entrypoint → Run engine: starts · CLI entrypoints hand off parsed commands and flags to the run engine.
- Run engine → Content extraction: extracts · The run layer uses shared extraction for URLs and media pages.
- Run engine → Transcript engine: loads transcripts · The run layer resolves transcripts before LLM summarization.
- Run engine → Prompt kit: builds prompts · Prompt templates shape summary and extract-only output.
- Run engine → LLM layer: generates · The run engine streams text or JSON through provider abstractions.
- Run engine → Slides pipeline: renders slides · URL flows can branch into slide extraction and slide output rendering.
- Run engine → URL flow: routes url · URL inputs are processed through the URL flow.
- Run engine → Asset flow: routes asset · Files and local media are processed through the asset flow.
- Daemon server → Daemon runtime: serves · HTTP/SSE endpoints expose the daemon runtime to clients.
- Daemon runtime → Content extraction: reuses · Daemon-backed requests use the same extraction layer as the CLI.
- Daemon runtime → Transcript engine: reuses · Daemon-backed requests use the shared transcript pipeline.
- Daemon runtime → LLM layer: summarizes · The daemon delegates model execution to the shared LLM layer.
- Side panel → Background bridge: messages · The side panel talks to the background layer for tab and daemon actions.
- Background bridge → Daemon server: calls localhost · The extension reaches the local daemon over token-authenticated HTTP/SSE.
- Background bridge → Content scripts: coordinates tab · Background scripts bridge panel state with content-script extraction and automation.
- Side panel → Extension contracts: shares contracts · Panel UI relies on shared extension payload and state contracts.
- Options page → Extension contracts: shares contracts · Options UI uses the same settings, status, and persistence helpers.
- Content scripts → Content extraction: extracts pages · Content scripts feed page data into the shared extraction logic.
- Content extraction → Transcript engine: prefers transcripts · Media-aware extraction can hand off to transcript discovery and normalization.
- Transcript engine → Transcription providers: falls back · When transcripts are unavailable, transcription providers are used.
- Content extraction → Shared contracts: serializes · Extraction and stream results are shaped by shared contracts.
- Transcript engine → Shared contracts: serializes · Transcript and timestamp payloads use shared contracts.
- Side panel → Shared contracts: consumes · The panel renders SSE, summary, and slides payloads from shared contracts.
- Docs site → CLI entrypoint: documents · Docs cover CLI usage and operational flows.
- Docs site → Side panel: documents · Docs explain extension behavior and browser support.
- CI & release → CLI entrypoint: builds · Workspace tooling and CI produce the CLI and daemon artifacts.
- CI & release → Side panel: builds · CI and release tooling also package the browser extension.
