# justatalentedguy/cp-brain architecture

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

- Interactive diagram: https://gitdiagram.com/justatalentedguy/cp-brain
- Repository: https://github.com/justatalentedguy/cp-brain

## Overview

CP Brain is a local competitive-programming workspace integrated with VS Code. A user captures solution context and ideas in the extension; durable outboxes support delivery to the local archive, where lifecycle tracking and knowledge management preserve them. The dashboard supports review, contest workflows, search, and optional analysis: users can inspect sharing choices, prepare work, and manage jobs. The README also documents Codeforces sync and optional Groq suggestions. Edges are limited to relationships shown in excerpts, SOURCE INDEX references, or the README; some service capabilities are documented but their internal wiring was not sampled.

Main entry points: [`packages/dashboard/src/api.ts`](https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/api.ts) (Dashboard API), [`packages/service/src/server.ts`](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/server.ts) (Local Service), [`packages/extension/src/extension.ts`](https://github.com/justatalentedguy/cp-brain/blob/main/packages/extension/src/extension.ts) (Extension Host), [`packages/service/src/queue.ts`](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/queue.ts) (Analysis Queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["VS Code Capture"]
  node_capture_ext["Capture<br/>[capture.ts]"]
  node_extension_host["Extension Host<br/>[extension.ts]"]
  node_disk_outbox[("Disk Outbox<br/>[outbox.ts]")]
  node_transport["Capture Transport<br/>[transport.ts]"]
  node_webview["Dashboard Bridge<br/>[webview.ts]"]
end

subgraph group_archive["Local Archive"]
  node_server["Local Service<br/>[server.ts]"]
  node_store[("Archive Store<br/>[store.ts]")]
  node_lifecycle["Learning Episodes<br/>[lifecycle.ts]"]
  node_knowledge_service["Knowledge Library<br/>[knowledge.ts]"]
  node_imports["Workspace Import<br/>[imports.ts]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_app["Dashboard App<br/>[main.tsx]"]
  node_dashboard_api["Dashboard API<br/>[api.ts]"]
  node_browser_outbox[("Browser Outbox<br/>[outbox.ts]")]
end

subgraph group_analysis["Analysis and Search"]
  node_analysis_ui["Analysis Workbench<br/>[analysis.tsx]"]
  node_preparation["Preparation<br/>[preparation.ts]"]
  node_job_queue[("Analysis Queue<br/>[queue.ts]")]
  node_search_ui["Knowledge Search<br/>[search.tsx]"]
  node_search_service["Search Service<br/>[search.ts]"]
  node_semantic["Semantic Retrieval<br/>[semantic.ts]"]
end

subgraph group_contest["Contest Workflows"]
  node_contest_service["Contest Review<br/>[contests.ts]"]
  node_contest_ui["Contest Dashboard<br/>[contests.tsx]"]
  node_narratives["Narratives<br/>[narratives.ts]"]
end

node_programmer(("Programmer"))
node_vscode["VS Code"]
node_codeforces["Codeforces"]
node_groq["Groq Provider"]

node_programmer -->|"uses"| node_vscode
node_vscode -->|"hosts"| node_extension_host
node_extension_host -->|"invokes"| node_capture_ext
node_capture_ext -->|"persists captures"| node_disk_outbox
node_extension_host -->|"uses"| node_transport
node_transport -->|"drains"| node_disk_outbox
node_extension_host -->|"opens dashboard"| node_webview
node_webview -->|"bridges requests"| node_dashboard_api
node_programmer -->|"reviews workspace"| node_dashboard_app
node_dashboard_app -->|"loads and mutates"| node_dashboard_api
node_dashboard_api -->|"queues events"| node_browser_outbox
node_dashboard_api -.->|"sends API requests"| node_server
node_server -->|"uses archive"| node_store
node_server -->|"routes workspace import"| node_imports
node_server -->|"routes knowledge"| node_knowledge_service
node_lifecycle -.->|"persists state"| node_store
node_server -->|"routes analysis jobs"| node_job_queue
node_analysis_ui -->|"submits workflows"| node_dashboard_api
node_analysis_ui -->|"requests preparation"| node_preparation
node_preparation -->|"enqueues work"| node_job_queue
node_job_queue -.->|"requests hosted analysis"| node_groq
node_search_ui -->|"queries"| node_dashboard_api
node_dashboard_api -.->|"routes search"| node_search_service
node_search_service -->|"uses semantic retrieval"| node_semantic
node_contest_ui -->|"loads contest data"| node_dashboard_api
node_contest_service -->|"reads and writes"| node_store
node_contest_ui -->|"views narratives"| node_narratives
node_programmer -->|"connects account"| node_codeforces
node_server -.->|"syncs public data"| node_codeforces

click node_capture_ext "https://github.com/justatalentedguy/cp-brain/blob/main/packages/extension/src/capture.ts"
click node_extension_host "https://github.com/justatalentedguy/cp-brain/blob/main/packages/extension/src/extension.ts"
click node_disk_outbox "https://github.com/justatalentedguy/cp-brain/blob/main/packages/extension/src/outbox.ts"
click node_transport "https://github.com/justatalentedguy/cp-brain/blob/main/packages/extension/src/transport.ts"
click node_webview "https://github.com/justatalentedguy/cp-brain/blob/main/packages/extension/src/webview.ts"
click node_server "https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/server.ts"
click node_store "https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/store.ts"
click node_lifecycle "https://github.com/justatalentedguy/cp-brain/blob/main/packages/core/src/lifecycle.ts"
click node_knowledge_service "https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/knowledge.ts"
click node_imports "https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/imports.ts"
click node_dashboard_app "https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/main.tsx"
click node_dashboard_api "https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/api.ts"
click node_browser_outbox "https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/outbox.ts"
click node_analysis_ui "https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/analysis.tsx"
click node_preparation "https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/preparation.ts"
click node_job_queue "https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/queue.ts"
click node_search_ui "https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/search.tsx"
click node_search_service "https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/search.ts"
click node_semantic "https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/semantic.ts"
click node_contest_service "https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/contests.ts"
click node_contest_ui "https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/contests.tsx"
click node_narratives "https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/narratives.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_capture_ext,node_extension_host,node_disk_outbox,node_transport,node_webview toneBlue
class node_server,node_store,node_lifecycle,node_knowledge_service,node_imports toneAmber
class node_dashboard_app,node_dashboard_api,node_browser_outbox toneMint
class node_analysis_ui,node_preparation,node_job_queue,node_search_ui,node_search_service,node_semantic toneRose
class node_contest_service,node_contest_ui,node_narratives,node_programmer,node_vscode,node_codeforces,node_groq toneIndigo
```

## Components

### VS Code Capture

- [Capture](https://github.com/justatalentedguy/cp-brain/blob/main/packages/extension/src/capture.ts): `packages/extension/src/capture.ts`
- [Extension Host](https://github.com/justatalentedguy/cp-brain/blob/main/packages/extension/src/extension.ts): `packages/extension/src/extension.ts`
- [Disk Outbox](https://github.com/justatalentedguy/cp-brain/blob/main/packages/extension/src/outbox.ts): `packages/extension/src/outbox.ts`
- [Capture Transport](https://github.com/justatalentedguy/cp-brain/blob/main/packages/extension/src/transport.ts): `packages/extension/src/transport.ts`
- [Dashboard Bridge](https://github.com/justatalentedguy/cp-brain/blob/main/packages/extension/src/webview.ts): `packages/extension/src/webview.ts`

### Local Archive

- [Local Service](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/server.ts): `packages/service/src/server.ts`
- [Archive Store](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/store.ts): `packages/service/src/store.ts`
- [Learning Episodes](https://github.com/justatalentedguy/cp-brain/blob/main/packages/core/src/lifecycle.ts): `packages/core/src/lifecycle.ts`
- [Knowledge Library](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/knowledge.ts): `packages/service/src/knowledge.ts`
- [Workspace Import](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/imports.ts): `packages/service/src/imports.ts`

### Dashboard

- [Dashboard App](https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/main.tsx): `packages/dashboard/src/main.tsx`
- [Dashboard API](https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/api.ts): `packages/dashboard/src/api.ts`
- [Browser Outbox](https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/outbox.ts): `packages/dashboard/src/outbox.ts`

### Analysis and Search

- [Analysis Workbench](https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/analysis.tsx): `packages/dashboard/src/analysis.tsx`
- [Preparation](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/preparation.ts): `packages/service/src/preparation.ts`
- [Analysis Queue](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/queue.ts): `packages/service/src/queue.ts`
- [Knowledge Search](https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/search.tsx): `packages/dashboard/src/search.tsx`
- [Search Service](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/search.ts): `packages/service/src/search.ts`
- [Semantic Retrieval](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/semantic.ts): `packages/service/src/semantic.ts`

### Contest Workflows

- [Contest Review](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/contests.ts): `packages/service/src/contests.ts`
- [Contest Dashboard](https://github.com/justatalentedguy/cp-brain/blob/main/packages/dashboard/src/contests.tsx): `packages/dashboard/src/contests.tsx`
- [Narratives](https://github.com/justatalentedguy/cp-brain/blob/main/packages/service/src/narratives.ts): `packages/service/src/narratives.ts`

### Other components

- **Programmer**
- **VS Code**
- **Codeforces**
- **Groq Provider**

## Connections

- Programmer → VS Code: uses
- VS Code → Extension Host: hosts (evidence: `packages/extension/src/extension.ts`)
- Extension Host → Capture: invokes (evidence: `packages/extension/src/extension.ts`)
- Capture → Disk Outbox: persists captures (evidence: `packages/extension/src/capture.ts`)
- Extension Host → Capture Transport: uses (evidence: `packages/extension/src/extension.ts`)
- Capture Transport → Disk Outbox: drains (evidence: `packages/extension/src/transport.ts`)
- Extension Host → Dashboard Bridge: opens dashboard (evidence: `packages/extension/src/extension.ts`)
- Dashboard Bridge → Dashboard API: bridges requests (evidence: `packages/dashboard/src/api.ts`)
- Programmer → Dashboard App: reviews workspace
- Dashboard App → Dashboard API: loads and mutates (evidence: `packages/dashboard/src/main.tsx`)
- Dashboard API → Browser Outbox: queues events (evidence: `packages/dashboard/src/api.ts`)
- Dashboard API → Local Service: sends API requests
- Local Service → Archive Store: uses archive (evidence: `packages/service/src/server.ts`)
- Local Service → Workspace Import: routes workspace import (evidence: `packages/service/src/server.ts`)
- Local Service → Knowledge Library: routes knowledge (evidence: `packages/service/src/server.ts`)
- Learning Episodes → Archive Store: persists state
- Local Service → Analysis Queue: routes analysis jobs (evidence: `packages/service/src/server.ts`)
- Analysis Workbench → Dashboard API: submits workflows (evidence: `packages/dashboard/src/analysis.tsx`)
- Analysis Workbench → Preparation: requests preparation (evidence: `packages/dashboard/src/analysis.tsx`)
- Preparation → Analysis Queue: enqueues work (evidence: `packages/service/src/preparation.ts`)
- Analysis Queue → Groq Provider: requests hosted analysis
- Knowledge Search → Dashboard API: queries (evidence: `packages/dashboard/src/search.tsx`)
- Dashboard API → Search Service: routes search
- Search Service → Semantic Retrieval: uses semantic retrieval (evidence: `packages/service/src/search.ts`)
- Contest Dashboard → Dashboard API: loads contest data (evidence: `packages/dashboard/src/contests.tsx`)
- Contest Review → Archive Store: reads and writes (evidence: `packages/service/src/contests.ts`)
- Contest Dashboard → Narratives: views narratives
- Programmer → Codeforces: connects account
- Local Service → Codeforces: syncs public data