# stahl-g/briefloop architecture

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

- Interactive diagram: https://gitdiagram.com/stahl-g/briefloop
- Repository: https://github.com/stahl-g/briefloop

## Overview

BriefLoop is a local-first reporting workbench for industry research, strategy, and investor-relations users. The main workflow is to create a report, provide or retrieve materials, run research and drafting through a selected local runtime, inspect evidence and independent review, revise, and save or export the result. The README also documents chat, MCP material intake, learning roles, templates, and desktop support, so these appear as distinct branches. Wiring reflects README-described capabilities and sampled entry points; unsampled implementation details are not inferred.

Main entry points: [`src/briefloop/app_server.py`](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/app_server.py) (Report tasks), [`src/briefloop/store.py`](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/store.py) (Workspace store), [`src/briefloop/server.py`](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/server.py) (Local API), [`src/briefloop/static/app.js`](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/static/app.js) (Web interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_webui["Web interface<br/>[app.js]"]
  node_api["Local API<br/>[server.py]"]
  node_desktop["Desktop shell<br/>[main.cjs]"]
end

subgraph group_workspace["Workspace data"]
  node_workspace_store[("Workspace store<br/>[store.py]")]
  node_upload["Source intake"]
  node_source_processing["Source processing"]
end

subgraph group_research["Research execution"]
  node_report_task["Report tasks<br/>[app_server.py]"]
  node_source_search["Source search<br/>[source_search.py]"]
  node_search_policy["Search policy<br/>[search_policy.py]"]
  node_research_plan["Research planning<br/>[research_plan.py]"]
  node_scout["Scout research<br/>[scout.py]"]
  node_analyst["Analyst drafting<br/>[analyst.py]"]
  node_chat["Agent conversation<br/>[chat_dispatch.py]"]
end

subgraph group_review["Review and output"]
  node_evidence["Evidence tracking<br/>[evidence.py]"]
  node_review["Independent review<br/>[review.py]"]
  node_revision["Revision<br/>[revision_policy.py]"]
  node_delivery["Document export<br/>[document_export.py]"]
  node_learning["Learning roles<br/>[engine.py]"]
  node_templates["Report templates<br/>[templates.py]"]
end

subgraph group_integrations["Runtime integrations"]
  node_connectors["MCP materials<br/>[service.py]"]
  node_runtime["Runtime dispatch<br/>[runtime.py]"]
end

node_user(("Researcher"))
node_external_search(("Search services"))
node_model_host(("Model host"))
node_mcp_service(("MCP service"))

node_user -->|"submits work"| node_webui
node_webui -->|"sends requests"| node_api
node_api -->|"reads and writes"| node_workspace_store
node_api -->|"dispatches tasks"| node_report_task
node_report_task -->|"admits materials"| node_upload
node_upload -->|"records sources"| node_workspace_store
node_report_task -->|"plans research"| node_research_plan
node_report_task -->|"requests sources"| node_source_search
node_source_search -->|"checks channels"| node_search_policy
node_source_search -.->|"searches"| node_external_search
node_report_task -->|"requests selected materials"| node_connectors
node_connectors -.->|"calls tools"| node_mcp_service
node_connectors -->|"records receipts"| node_workspace_store
node_report_task -->|"delegates research"| node_scout
node_report_task -->|"delegates drafting"| node_analyst
node_report_task -->|"selects execution"| node_runtime
node_runtime -.->|"runs model tasks"| node_model_host
node_webui -->|"sends messages"| node_chat
node_chat -->|"executes turns"| node_runtime
node_source_processing -->|"saves extracted content"| node_workspace_store
node_report_task -->|"tracks cited support"| node_evidence
node_report_task -->|"requests assessment"| node_review
node_review -->|"saves review"| node_workspace_store
node_report_task -->|"applies revision policy"| node_revision
node_report_task -->|"exports report"| node_delivery
node_delivery -->|"reads report data"| node_workspace_store
node_user -->|"chooses format"| node_templates
node_report_task -->|"uses report format"| node_templates
node_user -->|"requests learning"| node_learning
node_user -->|"opens workspace"| node_desktop
node_desktop -->|"hosts local service"| node_api

click node_webui "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/static/app.js"
click node_api "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/server.py"
click node_report_task "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/app_server.py"
click node_workspace_store "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/store.py"
click node_upload "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/source_ingestion.py"
click node_source_processing "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/source_extraction.py"
click node_source_search "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/source_search.py"
click node_search_policy "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/search_policy.py"
click node_connectors "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/connectors/service.py"
click node_research_plan "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/research_plan.py"
click node_scout "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/scout.py"
click node_analyst "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/analyst.py"
click node_runtime "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/runtime.py"
click node_chat "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/chat_dispatch.py"
click node_evidence "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/evidence.py"
click node_review "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/review.py"
click node_revision "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/revision_policy.py"
click node_delivery "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/document_export.py"
click node_learning "https://github.com/stahl-g/briefloop/blob/main/src/wikiskill/engine.py"
click node_templates "https://github.com/stahl-g/briefloop/blob/main/src/briefloop/templates.py"
click node_desktop "https://github.com/stahl-g/briefloop/blob/main/desktop/electron/main.cjs"

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_webui,node_api,node_desktop toneBlue
class node_workspace_store,node_upload,node_source_processing toneAmber
class node_report_task,node_source_search,node_search_policy,node_research_plan,node_scout,node_analyst,node_chat toneMint
class node_evidence,node_review,node_revision,node_delivery,node_learning,node_templates toneRose
class node_connectors,node_runtime,node_user,node_external_search,node_model_host,node_mcp_service toneIndigo
```

## Components

### User interface

- [Web interface](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/static/app.js): `src/briefloop/static/app.js`
- [Local API](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/server.py): `src/briefloop/server.py`
- [Desktop shell](https://github.com/stahl-g/briefloop/blob/main/desktop/electron/main.cjs): `desktop/electron/main.cjs`

### Workspace data

- [Workspace store](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/store.py): `src/briefloop/store.py`
- [Source intake](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/source_ingestion.py): `src/briefloop/source_ingestion.py`
- [Source processing](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/source_extraction.py): `src/briefloop/source_extraction.py`

### Research execution

- [Report tasks](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/app_server.py): `src/briefloop/app_server.py`
- [Source search](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/source_search.py): `src/briefloop/source_search.py`
- [Search policy](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/search_policy.py): `src/briefloop/search_policy.py`
- [Research planning](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/research_plan.py): `src/briefloop/research_plan.py`
- [Scout research](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/scout.py): `src/briefloop/scout.py`
- [Analyst drafting](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/analyst.py): `src/briefloop/analyst.py`
- [Agent conversation](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/chat_dispatch.py): `src/briefloop/chat_dispatch.py`

### Review and output

- [Evidence tracking](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/evidence.py): `src/briefloop/evidence.py`
- [Independent review](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/review.py): `src/briefloop/review.py`
- [Revision](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/revision_policy.py): `src/briefloop/revision_policy.py`
- [Document export](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/document_export.py): `src/briefloop/document_export.py`
- [Learning roles](https://github.com/stahl-g/briefloop/blob/main/src/wikiskill/engine.py): `src/wikiskill/engine.py`
- [Report templates](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/templates.py): `src/briefloop/templates.py`

### Runtime integrations

- [MCP materials](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/connectors/service.py): `src/briefloop/connectors/service.py`
- [Runtime dispatch](https://github.com/stahl-g/briefloop/blob/main/src/briefloop/runtime.py): `src/briefloop/runtime.py`

### Other components

- **Researcher**
- **Search services**
- **Model host**
- **MCP service**

## Connections

- Researcher → Web interface: submits work
- Web interface → Local API: sends requests
- Local API → Workspace store: reads and writes
- Local API → Report tasks: dispatches tasks
- Report tasks → Source intake: admits materials
- Source intake → Workspace store: records sources
- Report tasks → Research planning: plans research
- Report tasks → Source search: requests sources
- Source search → Search policy: checks channels
- Source search → Search services: searches
- Report tasks → MCP materials: requests selected materials
- MCP materials → MCP service: calls tools
- MCP materials → Workspace store: records receipts
- Report tasks → Scout research: delegates research
- Report tasks → Analyst drafting: delegates drafting
- Report tasks → Runtime dispatch: selects execution
- Runtime dispatch → Model host: runs model tasks
- Web interface → Agent conversation: sends messages
- Agent conversation → Runtime dispatch: executes turns
- Source processing → Workspace store: saves extracted content
- Report tasks → Evidence tracking: tracks cited support
- Report tasks → Independent review: requests assessment
- Independent review → Workspace store: saves review
- Report tasks → Revision: applies revision policy
- Report tasks → Document export: exports report
- Document export → Workspace store: reads report data
- Researcher → Report templates: chooses format
- Report tasks → Report templates: uses report format
- Researcher → Learning roles: requests learning
- Researcher → Desktop shell: opens workspace
- Desktop shell → Local API: hosts local service