# razi2001/brief architecture

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

- Interactive diagram: https://gitdiagram.com/razi2001/brief
- Repository: https://github.com/razi2001/brief

## Overview

Brief is a browser-extension and web service for capturing bug evidence, generating a ticket, and filing it to an issue tracker. The central workflow runs from extension capture and draft editing through upload, server-side transcription and ticket composition, then tracker filing and ticket review. Replay capture and team workflows are additional product branches. Edges reflect README claims and the supplied excerpts/index; unsampled implementation details are represented only at supported directory scope.

Main entry points: [`extension/background.js`](https://github.com/razi2001/brief/blob/main/extension/background.js) (Extension worker), [`extension/popup.js`](https://github.com/razi2001/brief/blob/main/extension/popup.js) (Capture popup), [`extension/cloud.js`](https://github.com/razi2001/brief/blob/main/extension/cloud.js) (Cloud client), [`web/lib/agent/process-brief.ts`](https://github.com/razi2001/brief/blob/main/web/lib/agent/process-brief.ts) (Ticket processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Extension capture"]
  node_popup["Capture popup<br/>[popup.js]"]
  node_worker["Extension worker<br/>[background.js]"]
  node_draft[("Draft state<br/>[draft.js]")]
  node_evidence[("Evidence files<br/>[filestore.js]")]
  node_editor["Evidence editor<br/>[shot-editor.js]"]
  node_capture_pages["Tab capture<br/>[page-capture.js]"]
  node_replay_sites["Replay site rules<br/>[replay-sites.js]"]
  node_replay_capture["Replay capture<br/>[replay.js]"]
  node_replay_data[("Replay assets<br/>[replay-store.js]")]
  node_cloud_client["Cloud client<br/>[cloud.js]"]
end

subgraph group_service["Brief service"]
  node_brief_api["Brief API<br/>[route.ts]"]
  node_transcribe_api["Transcription API<br/>[route.ts]"]
  node_processing["Ticket processing<br/>[process-brief.ts]"]
  node_context["Evidence context<br/>[context-block.ts]"]
  node_transcription["Speech transcription<br/>[transcribe.ts]"]
  node_brief_store[("Brief storage<br/>[brief-store.ts]")]
  node_filing["Tracker filing<br/>[brief-filing.ts]"]
end

subgraph group_trackers["Tracker integrations"]
  node_tracker_registry["Tracker adapters<br/>[registry.ts]"]
  node_external_trackers["Issue trackers"]
end

subgraph group_web["Web app"]
  node_onboarding["Setup wizard<br/>[Onboarding.tsx]"]
  node_connections["Tracker connections"]
  node_brief_pages["Ticket views<br/>[BriefPage.tsx]"]
  node_replay_player["Replay player<br/>[ReplayPlayer.tsx]"]
  node_team_workflows["Team workflows<br/>[page.tsx]"]
end

node_reporter(("Reporter"))
node_web_user(("Web user"))

node_reporter -->|"captures bug"| node_popup
node_popup -->|"updates draft"| node_draft
node_popup -->|"stores evidence"| node_evidence
node_popup -->|"transcribes note"| node_cloud_client
node_worker -->|"updates draft"| node_draft
node_worker -->|"stores captures"| node_evidence
node_worker -->|"captures tab"| node_capture_pages
node_worker -->|"checks rules"| node_replay_sites
node_worker -->|"files brief"| node_filing
node_editor -.->|"saves edits"| node_evidence
node_replay_sites -->|"fetches site rules"| node_cloud_client
node_replay_capture -.->|"stores replay"| node_replay_data
node_reporter -.->|"edits evidence"| node_editor
node_cloud_client -->|"creates brief"| node_brief_api
node_cloud_client -->|"sends audio"| node_transcribe_api
node_brief_api -.->|"persists brief"| node_brief_store
node_transcribe_api -.->|"transcribes audio"| node_transcription
node_processing -->|"builds context"| node_context
node_context -->|"uses transcript"| node_transcription
node_processing -.->|"loads brief"| node_brief_store
node_processing -.->|"composes ticket"| node_filing
node_filing -.->|"selects adapter"| node_tracker_registry
node_tracker_registry -.->|"files ticket"| node_external_trackers
node_web_user -->|"sets up account"| node_onboarding
node_onboarding -->|"connects tracker"| node_connections
node_web_user -->|"reviews ticket"| node_brief_pages
node_web_user -.->|"views replay"| node_replay_player
node_web_user -.->|"joins team activity"| node_team_workflows

click node_popup "https://github.com/razi2001/brief/blob/main/extension/popup.js"
click node_worker "https://github.com/razi2001/brief/blob/main/extension/background.js"
click node_draft "https://github.com/razi2001/brief/blob/main/extension/draft.js"
click node_evidence "https://github.com/razi2001/brief/blob/main/extension/filestore.js"
click node_editor "https://github.com/razi2001/brief/blob/main/extension/editor/shot-editor.js"
click node_capture_pages "https://github.com/razi2001/brief/blob/main/extension/page-capture.js"
click node_replay_sites "https://github.com/razi2001/brief/blob/main/extension/replay-sites.js"
click node_replay_capture "https://github.com/razi2001/brief/blob/main/extension/replay.js"
click node_replay_data "https://github.com/razi2001/brief/blob/main/extension/replay-store.js"
click node_cloud_client "https://github.com/razi2001/brief/blob/main/extension/cloud.js"
click node_brief_api "https://github.com/razi2001/brief/blob/main/web/app/api/briefs/route.ts"
click node_transcribe_api "https://github.com/razi2001/brief/blob/main/web/app/api/transcribe/route.ts"
click node_processing "https://github.com/razi2001/brief/blob/main/web/lib/agent/process-brief.ts"
click node_context "https://github.com/razi2001/brief/blob/main/web/lib/agent/context-block.ts"
click node_transcription "https://github.com/razi2001/brief/blob/main/web/lib/agent/transcribe.ts"
click node_brief_store "https://github.com/razi2001/brief/blob/main/web/lib/agent/brief-store.ts"
click node_filing "https://github.com/razi2001/brief/blob/main/web/lib/brief-filing.ts"
click node_tracker_registry "https://github.com/razi2001/brief/blob/main/web/lib/trackers/registry.ts"
click node_onboarding "https://github.com/razi2001/brief/blob/main/web/components/Onboarding.tsx"
click node_connections "https://github.com/razi2001/brief/blob/main/web/components/useTrackerConnect.ts"
click node_brief_pages "https://github.com/razi2001/brief/blob/main/web/components/BriefPage.tsx"
click node_replay_player "https://github.com/razi2001/brief/blob/main/web/components/ReplayPlayer.tsx"
click node_team_workflows "https://github.com/razi2001/brief/blob/main/web/app/(main)/competition/page.tsx"

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_popup,node_worker,node_draft,node_evidence,node_editor,node_capture_pages,node_replay_sites,node_replay_capture,node_replay_data,node_cloud_client,node_web_user toneBlue
class node_brief_api,node_transcribe_api,node_processing,node_context,node_transcription,node_brief_store,node_filing toneAmber
class node_tracker_registry,node_external_trackers toneMint
class node_onboarding,node_connections,node_brief_pages,node_replay_player,node_team_workflows toneRose
class node_reporter toneIndigo
```

## Components

### Extension capture

- [Capture popup](https://github.com/razi2001/brief/blob/main/extension/popup.js): `extension/popup.js`
- [Extension worker](https://github.com/razi2001/brief/blob/main/extension/background.js): `extension/background.js`
- [Draft state](https://github.com/razi2001/brief/blob/main/extension/draft.js): `extension/draft.js`
- [Evidence files](https://github.com/razi2001/brief/blob/main/extension/filestore.js): `extension/filestore.js`
- [Evidence editor](https://github.com/razi2001/brief/blob/main/extension/editor/shot-editor.js): `extension/editor/shot-editor.js`
- [Tab capture](https://github.com/razi2001/brief/blob/main/extension/page-capture.js): `extension/page-capture.js`
- [Replay site rules](https://github.com/razi2001/brief/blob/main/extension/replay-sites.js): `extension/replay-sites.js`
- [Replay capture](https://github.com/razi2001/brief/blob/main/extension/replay.js): `extension/replay.js`
- [Replay assets](https://github.com/razi2001/brief/blob/main/extension/replay-store.js): `extension/replay-store.js`
- [Cloud client](https://github.com/razi2001/brief/blob/main/extension/cloud.js): `extension/cloud.js`

### Brief service

- [Brief API](https://github.com/razi2001/brief/blob/main/web/app/api/briefs/route.ts): `web/app/api/briefs/route.ts`
- [Transcription API](https://github.com/razi2001/brief/blob/main/web/app/api/transcribe/route.ts): `web/app/api/transcribe/route.ts`
- [Ticket processing](https://github.com/razi2001/brief/blob/main/web/lib/agent/process-brief.ts): `web/lib/agent/process-brief.ts`
- [Evidence context](https://github.com/razi2001/brief/blob/main/web/lib/agent/context-block.ts): `web/lib/agent/context-block.ts`
- [Speech transcription](https://github.com/razi2001/brief/blob/main/web/lib/agent/transcribe.ts): `web/lib/agent/transcribe.ts`
- [Brief storage](https://github.com/razi2001/brief/blob/main/web/lib/agent/brief-store.ts): `web/lib/agent/brief-store.ts`
- [Tracker filing](https://github.com/razi2001/brief/blob/main/web/lib/brief-filing.ts): `web/lib/brief-filing.ts`

### Tracker integrations

- [Tracker adapters](https://github.com/razi2001/brief/blob/main/web/lib/trackers/registry.ts): `web/lib/trackers/registry.ts`
- **Issue trackers**

### Web app

- [Setup wizard](https://github.com/razi2001/brief/blob/main/web/components/Onboarding.tsx): `web/components/Onboarding.tsx`
- [Tracker connections](https://github.com/razi2001/brief/blob/main/web/components/useTrackerConnect.ts): `web/components/useTrackerConnect.ts`
- [Ticket views](https://github.com/razi2001/brief/blob/main/web/components/BriefPage.tsx): `web/components/BriefPage.tsx`
- [Replay player](https://github.com/razi2001/brief/blob/main/web/components/ReplayPlayer.tsx): `web/components/ReplayPlayer.tsx`
- [Team workflows](https://github.com/razi2001/brief/blob/main/web/app/(main)/competition/page.tsx): `web/app/(main)/competition/page.tsx`

### Other components

- **Reporter**
- **Web user**

## Connections

- Reporter → Capture popup: captures bug
- Capture popup → Draft state: updates draft (evidence: `extension/popup.js`)
- Capture popup → Evidence files: stores evidence (evidence: `extension/popup.js`)
- Capture popup → Cloud client: transcribes note (evidence: `extension/popup.js`)
- Extension worker → Draft state: updates draft (evidence: `extension/background.js`)
- Extension worker → Evidence files: stores captures (evidence: `extension/background.js`)
- Extension worker → Tab capture: captures tab (evidence: `extension/background.js`)
- Extension worker → Replay site rules: checks rules (evidence: `extension/background.js`)
- Extension worker → Tracker filing: files brief (evidence: `extension/background.js`)
- Evidence editor → Evidence files: saves edits
- Replay site rules → Cloud client: fetches site rules (evidence: `extension/replay-sites.js`)
- Replay capture → Replay assets: stores replay
- Reporter → Evidence editor: edits evidence
- Cloud client → Brief API: creates brief (evidence: `extension/cloud.js`)
- Cloud client → Transcription API: sends audio (evidence: `extension/cloud.js`)
- Brief API → Brief storage: persists brief
- Transcription API → Speech transcription: transcribes audio
- Ticket processing → Evidence context: builds context (evidence: `web/lib/agent/context-block.ts`)
- Evidence context → Speech transcription: uses transcript (evidence: `web/lib/agent/context-block.ts`)
- Ticket processing → Brief storage: loads brief
- Ticket processing → Tracker filing: composes ticket
- Tracker filing → Tracker adapters: selects adapter
- Tracker adapters → Issue trackers: files ticket
- Web user → Setup wizard: sets up account
- Setup wizard → Tracker connections: connects tracker (evidence: `web/components/Onboarding.tsx`)
- Web user → Ticket views: reviews ticket
- Web user → Replay player: views replay
- Web user → Team workflows: joins team activity
