# prooflinedev/session-recorder-chrome-extension architecture

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

- Interactive diagram: https://gitdiagram.com/prooflinedev/session-recorder-chrome-extension
- Repository: https://github.com/prooflinedev/session-recorder-chrome-extension

## Overview

Session Recorder is a Chrome extension for capturing browser bug reproductions, annotating them, and turning sessions into reports or GitHub issues. The main workflow runs from the side panel through background capture and local session storage, then into report viewing/export or optional publishing and issue filing. Additional capabilities include page and screenshot annotation, transcription, AI summaries, and configurable personal or Proofline services. Edges reflect the supplied excerpts, source-index references, and README; unsampled implementation details are represented only where their subsystem is clear.

Main entry points: [`entrypoints/background.ts`](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/background.ts) (Capture coordinator), [`entrypoints/share/useShareReport.ts`](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/share/useShareReport.ts) (Share workflow), [`entrypoints/sidepanel/App.tsx`](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/sidepanel/App.tsx) (Recorder panel), [`entrypoints/report/main.ts`](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/report/main.ts) (Report viewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Recording and capture"]
  node_sidepanel["Recorder panel<br/>[App.tsx]"]
  node_background["Capture coordinator<br/>[background.ts]"]
  node_capture_sources["Browser capture"]
  node_annotation["Page annotations<br/>[point-overlay.ts]"]
  node_transcription["Speech transcription<br/>[index.ts]"]
end

subgraph group_reports["Reports and export"]
  node_report_view["Report viewer<br/>[main.ts]"]
  node_bundle["ZIP bundle builder<br/>[bundle.ts]"]
  node_markdown["Markdown renderer<br/>[markdown.ts]"]
  node_trimmer["Evidence trimming<br/>[trimmer.ts]"]
end

subgraph group_sharing["Sharing and integrations"]
  node_share_ui["Issue draft UI<br/>[App.tsx]"]
  node_share_workflow["Share workflow<br/>[useShareReport.ts]"]
  node_summary["AI summaries<br/>[summary.ts]"]
  node_publication["Report publishing<br/>[cloudflare.ts]"]
  node_github_filing["GitHub issue filing<br/>[github.ts]"]
  node_proofline_ai["Proofline AI client<br/>[ai.ts]"]
end

subgraph group_platform["Extension platform"]
  node_session_data["Session records<br/>[types.ts]"]
  node_storage[("Local session store<br/>[index.ts]")]
  node_messaging["Extension messaging<br/>[messaging.ts]"]
  node_settings["Service settings<br/>[settings.ts]"]
end

node_tester(("QA tester"))
node_cloudflare{{"Cloudflare Pages"}}
node_github{{"GitHub"}}
node_proofline{{"Proofline service"}}

node_tester -->|"starts recording"| node_sidepanel
node_sidepanel -->|"sends commands"| node_background
node_background -->|"coordinates capture"| node_capture_sources
node_background -.->|"routes events"| node_annotation
node_background -->|"dispatches transcription"| node_transcription
node_background -->|"persists session"| node_storage
node_background -->|"uses event types"| node_session_data
node_sidepanel -->|"uses contract"| node_messaging
node_background -->|"broadcasts updates"| node_messaging
node_annotation -->|"sends annotations"| node_messaging
node_tester -->|"marks evidence"| node_annotation
node_tester -->|"opens report"| node_report_view
node_report_view -->|"loads session data"| node_storage
node_report_view -->|"builds export"| node_bundle
node_bundle -->|"trims evidence"| node_trimmer
node_bundle -->|"renders report"| node_markdown
node_markdown -->|"renders event data"| node_session_data
node_tester -->|"files issue"| node_share_ui
node_share_ui -->|"uses filing workflow"| node_share_workflow
node_share_workflow -->|"loads session data"| node_storage
node_share_workflow -->|"prepares evidence"| node_summary
node_share_workflow -->|"publishes report"| node_publication
node_share_workflow -.->|"creates issue"| node_github_filing
node_share_workflow -->|"loads configuration"| node_settings
node_publication -.->|"uploads report"| node_cloudflare
node_github_filing -.->|"files issue"| node_github
node_transcription -->|"requests transcription"| node_proofline_ai
node_proofline_ai -.->|"calls service"| node_proofline
node_settings -.->|"supports connection"| node_proofline

click node_sidepanel "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/sidepanel/App.tsx"
click node_background "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/background.ts"
click node_capture_sources "https://github.com/prooflinedev/session-recorder-chrome-extension/tree/main/lib/capture"
click node_annotation "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/annotations/point-overlay.ts"
click node_transcription "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/transcription/index.ts"
click node_session_data "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/session/types.ts"
click node_storage "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/storage/index.ts"
click node_messaging "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/messaging.ts"
click node_report_view "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/report/main.ts"
click node_bundle "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/export/bundle.ts"
click node_markdown "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/export/markdown.ts"
click node_trimmer "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/export/trimmer.ts"
click node_share_ui "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/share/App.tsx"
click node_share_workflow "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/share/useShareReport.ts"
click node_summary "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/sharing/summary.ts"
click node_publication "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/sharing/cloudflare.ts"
click node_github_filing "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/sharing/github.ts"
click node_proofline_ai "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/proofline/ai.ts"
click node_settings "https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/sharing/settings.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_sidepanel,node_background,node_capture_sources,node_annotation,node_transcription toneBlue
class node_report_view,node_bundle,node_markdown,node_trimmer toneAmber
class node_share_ui,node_share_workflow,node_summary,node_publication,node_github_filing,node_proofline_ai toneMint
class node_session_data,node_storage,node_messaging,node_settings toneRose
class node_tester,node_cloudflare,node_github,node_proofline toneIndigo
```

## Components

### Recording and capture

- [Recorder panel](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/sidepanel/App.tsx): `entrypoints/sidepanel/App.tsx`
- [Capture coordinator](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/background.ts): `entrypoints/background.ts`
- [Browser capture](https://github.com/prooflinedev/session-recorder-chrome-extension/tree/main/lib/capture): `lib/capture`
- [Page annotations](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/annotations/point-overlay.ts): `lib/annotations/point-overlay.ts`
- [Speech transcription](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/transcription/index.ts): `lib/transcription/index.ts`

### Reports and export

- [Report viewer](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/report/main.ts): `entrypoints/report/main.ts`
- [ZIP bundle builder](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/export/bundle.ts): `lib/export/bundle.ts`
- [Markdown renderer](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/export/markdown.ts): `lib/export/markdown.ts`
- [Evidence trimming](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/export/trimmer.ts): `lib/export/trimmer.ts`

### Sharing and integrations

- [Issue draft UI](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/share/App.tsx): `entrypoints/share/App.tsx`
- [Share workflow](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/entrypoints/share/useShareReport.ts): `entrypoints/share/useShareReport.ts`
- [AI summaries](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/sharing/summary.ts): `lib/sharing/summary.ts`
- [Report publishing](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/sharing/cloudflare.ts): `lib/sharing/cloudflare.ts`
- [GitHub issue filing](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/sharing/github.ts): `lib/sharing/github.ts`
- [Proofline AI client](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/proofline/ai.ts): `lib/proofline/ai.ts`

### Extension platform

- [Session records](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/session/types.ts): `lib/session/types.ts`
- [Local session store](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/storage/index.ts): `lib/storage/index.ts`
- [Extension messaging](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/messaging.ts): `lib/messaging.ts`
- [Service settings](https://github.com/prooflinedev/session-recorder-chrome-extension/blob/main/lib/sharing/settings.ts): `lib/sharing/settings.ts`

### Other components

- **QA tester**
- **Cloudflare Pages**
- **GitHub**
- **Proofline service**

## Connections

- QA tester → Recorder panel: starts recording (evidence: `README.md`)
- Recorder panel → Capture coordinator: sends commands
- Capture coordinator → Browser capture: coordinates capture (evidence: `entrypoints/background.ts`)
- Capture coordinator → Page annotations: routes events
- Capture coordinator → Speech transcription: dispatches transcription (evidence: `entrypoints/background.ts`)
- Capture coordinator → Local session store: persists session (evidence: `entrypoints/background.ts`)
- Capture coordinator → Session records: uses event types (evidence: `entrypoints/background.ts`)
- Recorder panel → Extension messaging: uses contract
- Capture coordinator → Extension messaging: broadcasts updates (evidence: `entrypoints/background.ts`)
- Page annotations → Extension messaging: sends annotations (evidence: `lib/annotations/point-overlay.ts`)
- QA tester → Page annotations: marks evidence (evidence: `README.md`)
- QA tester → Report viewer: opens report (evidence: `README.md`)
- Report viewer → Local session store: loads session data (evidence: `entrypoints/report/main.ts`)
- Report viewer → ZIP bundle builder: builds export (evidence: `entrypoints/report/main.ts`)
- ZIP bundle builder → Evidence trimming: trims evidence (evidence: `lib/export/bundle.ts`)
- ZIP bundle builder → Markdown renderer: renders report (evidence: `lib/export/bundle.ts`)
- Markdown renderer → Session records: renders event data (evidence: `lib/export/markdown.ts`)
- QA tester → Issue draft UI: files issue (evidence: `README.md`)
- Issue draft UI → Share workflow: uses filing workflow (evidence: `entrypoints/share/App.tsx`)
- Share workflow → Local session store: loads session data (evidence: `entrypoints/share/useShareReport.ts`)
- Share workflow → AI summaries: prepares evidence (evidence: `entrypoints/share/useShareReport.ts`)
- Share workflow → Report publishing: publishes report (evidence: `entrypoints/share/useShareReport.ts`)
- Share workflow → GitHub issue filing: creates issue (evidence: `entrypoints/share/useShareReport.ts`)
- Share workflow → Service settings: loads configuration (evidence: `entrypoints/share/useShareReport.ts`)
- Report publishing → Cloudflare Pages: uploads report
- GitHub issue filing → GitHub: files issue
- Speech transcription → Proofline AI client: requests transcription (evidence: `lib/transcription/index.ts`)
- Proofline AI client → Proofline service: calls service
- Service settings → Proofline service: supports connection
