# modsetter/surfsense architecture

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

- Interactive diagram: https://gitdiagram.com/modsetter/surfsense
- Repository: https://github.com/modsetter/surfsense

## Overview

SurfSense is a privacy-focused desktop or self-hosted AI workspace for researching, transforming, and editing local documents. The README’s primary workflow is to add sources, then ask an agent to search, extract, or edit them. The graph preserves the documented ingestion, agent, studio, format-support, and plugin capabilities; source-level edges are limited to relationships visible in the supplied excerpts or source index. Several subsystems are represented by their exact enclosing directories because their implementation files were not sampled.

Main entry points: [`backend/plugins/proprietary`](https://github.com/modsetter/surfsense/tree/main/backend/plugins/proprietary) (Scraping plugins), [`surfsense_local/backend/modules/agent/engines`](https://github.com/modsetter/surfsense/tree/main/surfsense_local/backend/modules/agent/engines) (Agent engines), [`surfsense_local/backend/worker/ingestion/pipeline.py`](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/worker/ingestion/pipeline.py) (Document ingestion), [`surfsense_local/backend/modules/agent/agent_threads/turn.py`](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/agent/agent_threads/turn.py) (Agent turns)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Local app"]
  node_frontend["Desktop UI<br/>[App.tsx]"]
  node_api["Local API<br/>[main.py]"]
  node_dependencies["API dependencies<br/>[dependencies.py]"]
  node_config["Local configuration<br/>[config.py]"]
  node_database[("Local database<br/>[db.py]")]
end

subgraph group_documents["Documents and studio"]
  node_storage["Document storage<br/>[storage.py]"]
  node_ingestion["Document ingestion<br/>[pipeline.py]"]
  node_studio["Studio pipelines"]
  node_office["Office conversion<br/>[engine.py]"]
end

subgraph group_agent["Agent and models"]
  node_agent_choice["Engine selection<br/>[engine_choice.py]"]
  node_thread_state["Thread state"]
  node_agent_engine["Agent engines"]
  node_ready_renders["Ready renders<br/>[ready_renders.py]"]
  node_replies["Agent replies<br/>[replies.py]"]
  node_turn["Agent turns<br/>[turn.py]"]
  node_chat_models[("Chat records<br/>[models.py]")]
end

subgraph group_plugins["Plugin ecosystem"]
  node_plugin_cli["Plugin CLI"]
  node_manifest["Plugin manifests"]
  node_plugin_sdk["Plugin SDK"]
  node_plugin_host["Plugin host<br/>[app.py]"]
  node_usage_meter[("Usage metering<br/>[usage_meter.py]")]
  node_mcp_progress["MCP progress<br/>[progress.py]"]
  node_mcp_results["MCP results<br/>[results.py]"]
  node_scraping_plugins["Scraping plugins"]
  node_license_access["Plugin license access<br/>[license_access.py]"]
end

subgraph group_services["Services and licensing"]
  node_license_router["License service<br/>[router.py]"]
  node_server["Backend server<br/>[app.py]"]
end

node_user(("User"))
node_model_provider(("Model provider"))
node_external_web(("External websites"))

node_user -->|"adds sources"| node_frontend
node_user -->|"asks agent"| node_frontend
node_frontend -.->|"requests work"| node_api
node_api -.->|"resolves dependencies"| node_dependencies
node_ingestion -.->|"reads document bytes"| node_storage
node_ingestion -.->|"records ingest state"| node_database
node_ingestion -->|"queues figure pass"| node_studio
node_studio -.->|"uses conversion"| node_office
node_agent_choice -->|"checks settings"| node_dependencies
node_agent_choice -.->|"selects engine"| node_agent_engine
node_agent_engine -->|"runs turn"| node_turn
node_agent_engine -->|"loads thread state"| node_thread_state
node_agent_engine -->|"reads thread records"| node_chat_models
node_turn -.->|"renders turn"| node_ready_renders
node_turn -.->|"emits replies"| node_replies
node_plugin_cli -.->|"loads manifest"| node_manifest
node_plugin_cli -.->|"invokes plugin"| node_plugin_sdk
node_server -->|"mounts host"| node_plugin_host
node_plugin_host -->|"starts meter"| node_usage_meter
node_plugin_host -.->|"mounts plugin routes"| node_scraping_plugins
node_scraping_plugins -->|"reports progress"| node_mcp_progress
node_scraping_plugins -->|"formats results"| node_mcp_results
node_scraping_plugins -->|"checks access"| node_license_access
node_scraping_plugins -.->|"fetches public data"| node_external_web
node_server -->|"mounts portal"| node_license_router
node_model_provider -.->|"provides model"| node_agent_engine

click node_frontend "https://github.com/modsetter/surfsense/blob/main/surfsense_local/frontend/src/App.tsx"
click node_api "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/api/main.py"
click node_dependencies "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/api/dependencies.py"
click node_config "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/shared/config.py"
click node_database "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/shared/db.py"
click node_storage "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/documents/storage.py"
click node_ingestion "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/worker/ingestion/pipeline.py"
click node_studio "https://github.com/modsetter/surfsense/tree/main/surfsense_local/backend/worker/studio"
click node_office "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/office_support/engine.py"
click node_agent_choice "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/agent/engine_choice.py"
click node_thread_state "https://github.com/modsetter/surfsense/tree/main/surfsense_local/backend/modules/agent/agent_threads"
click node_agent_engine "https://github.com/modsetter/surfsense/tree/main/surfsense_local/backend/modules/agent/engines"
click node_ready_renders "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/agent/agent_threads/ready_renders.py"
click node_replies "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/agent/agent_threads/replies.py"
click node_turn "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/agent/agent_threads/turn.py"
click node_chat_models "https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/chat/models.py"
click node_plugin_cli "https://github.com/modsetter/surfsense/tree/main/backend/plugins/bundles/core/cli/surfsense_plugin_cli"
click node_manifest "https://github.com/modsetter/surfsense/tree/main/backend/plugins/bundles/core/manifest/surfsense_plugin_manifest"
click node_plugin_sdk "https://github.com/modsetter/surfsense/tree/main/backend/plugins/bundles/core/sdk/surfsense_plugin_sdk"
click node_plugin_host "https://github.com/modsetter/surfsense/blob/main/backend/plugins/host/app.py"
click node_usage_meter "https://github.com/modsetter/surfsense/blob/main/backend/plugins/host/usage_meter/usage_meter.py"
click node_mcp_progress "https://github.com/modsetter/surfsense/blob/main/backend/plugins/mcp_server/progress.py"
click node_mcp_results "https://github.com/modsetter/surfsense/blob/main/backend/plugins/mcp_server/results.py"
click node_scraping_plugins "https://github.com/modsetter/surfsense/tree/main/backend/plugins/proprietary"
click node_license_access "https://github.com/modsetter/surfsense/blob/main/backend/plugins/proprietary/license_check/license_access.py"
click node_license_router "https://github.com/modsetter/surfsense/blob/main/backend/license/router.py"
click node_server "https://github.com/modsetter/surfsense/blob/main/backend/server/app.py"

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_frontend,node_api,node_dependencies,node_config,node_database,node_user toneBlue
class node_storage,node_ingestion,node_studio,node_office toneAmber
class node_agent_choice,node_thread_state,node_agent_engine,node_ready_renders,node_replies,node_turn,node_chat_models toneMint
class node_plugin_cli,node_manifest,node_plugin_sdk,node_plugin_host,node_usage_meter,node_mcp_progress,node_mcp_results,node_scraping_plugins,node_license_access toneRose
class node_license_router,node_server,node_model_provider,node_external_web toneIndigo
```

## Components

### Local app

- [Desktop UI](https://github.com/modsetter/surfsense/blob/main/surfsense_local/frontend/src/App.tsx): `surfsense_local/frontend/src/App.tsx`
- [Local API](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/api/main.py): `surfsense_local/backend/api/main.py`
- [API dependencies](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/api/dependencies.py): `surfsense_local/backend/api/dependencies.py`
- [Local configuration](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/shared/config.py): `surfsense_local/backend/shared/config.py`
- [Local database](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/shared/db.py): `surfsense_local/backend/shared/db.py`

### Documents and studio

- [Document storage](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/documents/storage.py): `surfsense_local/backend/modules/documents/storage.py`
- [Document ingestion](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/worker/ingestion/pipeline.py): `surfsense_local/backend/worker/ingestion/pipeline.py`
- [Studio pipelines](https://github.com/modsetter/surfsense/tree/main/surfsense_local/backend/worker/studio): `surfsense_local/backend/worker/studio`
- [Office conversion](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/office_support/engine.py): `surfsense_local/backend/modules/office_support/engine.py`

### Agent and models

- [Engine selection](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/agent/engine_choice.py): `surfsense_local/backend/modules/agent/engine_choice.py`
- [Thread state](https://github.com/modsetter/surfsense/tree/main/surfsense_local/backend/modules/agent/agent_threads): `surfsense_local/backend/modules/agent/agent_threads`
- [Agent engines](https://github.com/modsetter/surfsense/tree/main/surfsense_local/backend/modules/agent/engines): `surfsense_local/backend/modules/agent/engines`
- [Ready renders](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/agent/agent_threads/ready_renders.py): `surfsense_local/backend/modules/agent/agent_threads/ready_renders.py`
- [Agent replies](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/agent/agent_threads/replies.py): `surfsense_local/backend/modules/agent/agent_threads/replies.py`
- [Agent turns](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/agent/agent_threads/turn.py): `surfsense_local/backend/modules/agent/agent_threads/turn.py`
- [Chat records](https://github.com/modsetter/surfsense/blob/main/surfsense_local/backend/modules/chat/models.py): `surfsense_local/backend/modules/chat/models.py`

### Plugin ecosystem

- [Plugin CLI](https://github.com/modsetter/surfsense/tree/main/backend/plugins/bundles/core/cli/surfsense_plugin_cli): `backend/plugins/bundles/core/cli/surfsense_plugin_cli`
- [Plugin manifests](https://github.com/modsetter/surfsense/tree/main/backend/plugins/bundles/core/manifest/surfsense_plugin_manifest): `backend/plugins/bundles/core/manifest/surfsense_plugin_manifest`
- [Plugin SDK](https://github.com/modsetter/surfsense/tree/main/backend/plugins/bundles/core/sdk/surfsense_plugin_sdk): `backend/plugins/bundles/core/sdk/surfsense_plugin_sdk`
- [Plugin host](https://github.com/modsetter/surfsense/blob/main/backend/plugins/host/app.py): `backend/plugins/host/app.py`
- [Usage metering](https://github.com/modsetter/surfsense/blob/main/backend/plugins/host/usage_meter/usage_meter.py): `backend/plugins/host/usage_meter/usage_meter.py`
- [MCP progress](https://github.com/modsetter/surfsense/blob/main/backend/plugins/mcp_server/progress.py): `backend/plugins/mcp_server/progress.py`
- [MCP results](https://github.com/modsetter/surfsense/blob/main/backend/plugins/mcp_server/results.py): `backend/plugins/mcp_server/results.py`
- [Scraping plugins](https://github.com/modsetter/surfsense/tree/main/backend/plugins/proprietary): `backend/plugins/proprietary`
- [Plugin license access](https://github.com/modsetter/surfsense/blob/main/backend/plugins/proprietary/license_check/license_access.py): `backend/plugins/proprietary/license_check/license_access.py`

### Services and licensing

- [License service](https://github.com/modsetter/surfsense/blob/main/backend/license/router.py): `backend/license/router.py`
- [Backend server](https://github.com/modsetter/surfsense/blob/main/backend/server/app.py): `backend/server/app.py`

### Other components

- **User**
- **Model provider**
- **External websites**

## Connections

- User → Desktop UI: adds sources (evidence: `README.md`)
- User → Desktop UI: asks agent (evidence: `README.md`)
- Desktop UI → Local API: requests work
- Local API → API dependencies: resolves dependencies
- Document ingestion → Document storage: reads document bytes
- Document ingestion → Local database: records ingest state (evidence: `surfsense_local/backend/worker/ingestion/pipeline.py`)
- Document ingestion → Studio pipelines: queues figure pass (evidence: `surfsense_local/backend/worker/ingestion/pipeline.py`)
- Studio pipelines → Office conversion: uses conversion
- Engine selection → API dependencies: checks settings (evidence: `surfsense_local/backend/modules/agent/engine_choice.py`)
- Engine selection → Agent engines: selects engine
- Agent engines → Agent turns: runs turn (evidence: `surfsense_local/backend/modules/agent/engines/opencode_engine.py`)
- Agent engines → Thread state: loads thread state (evidence: `surfsense_local/backend/modules/agent/engines/opencode_engine.py`)
- Agent engines → Chat records: reads thread records (evidence: `surfsense_local/backend/modules/agent/engines/opencode_engine.py`)
- Agent turns → Ready renders: renders turn (evidence: `surfsense_local/backend/modules/agent/agent_threads/turn.py`)
- Agent turns → Agent replies: emits replies (evidence: `surfsense_local/backend/modules/agent/agent_threads/turn.py`)
- Plugin CLI → Plugin manifests: loads manifest
- Plugin CLI → Plugin SDK: invokes plugin
- Backend server → Plugin host: mounts host (evidence: `backend/server/app.py`)
- Plugin host → Usage metering: starts meter (evidence: `backend/plugins/host/app.py`)
- Plugin host → Scraping plugins: mounts plugin routes
- Scraping plugins → MCP progress: reports progress (evidence: `backend/plugins/proprietary/tiktok/server.py`)
- Scraping plugins → MCP results: formats results (evidence: `backend/plugins/proprietary/tiktok/server.py`)
- Scraping plugins → Plugin license access: checks access (evidence: `backend/plugins/proprietary/tiktok/server.py`)
- Scraping plugins → External websites: fetches public data
- Backend server → License service: mounts portal (evidence: `backend/server/app.py`)
- Model provider → Agent engines: provides model
