# henrydaum/second-brain architecture

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

- Interactive diagram: https://gitdiagram.com/henrydaum/second-brain
- Repository: https://github.com/henrydaum/second-brain

## Overview

Second Brain is a local, extensible AI agent with terminal and web chat surfaces. The main workflow is a user message entering through a frontend, being handled by the agent runtime and an LLM, and—when needed—using sandboxed extensions before a response is shown. Its broader product includes persistent conversations, configurable model connections, installable packages, scheduled tasks, file indexing, attachments, and sandboxed HTML widgets. The graph combines README-documented capabilities with relationships visible in indexed source references; several subsystem links are omitted where implementation was not sampled.

Main entry points: [`runtime/conversation_runtime.py`](https://github.com/henrydaum/second-brain/blob/main/runtime/conversation_runtime.py) (Agent runtime), [`sandbox/bridge.py`](https://github.com/henrydaum/second-brain/blob/main/sandbox/bridge.py) (Sandbox bridge), [`events/event_bus.py`](https://github.com/henrydaum/second-brain/blob/main/events/event_bus.py) (Event bus), [`runtime/session.py`](https://github.com/henrydaum/second-brain/blob/main/runtime/session.py) (Session state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_web["Web chat<br/>[App.tsx]"]
  node_http["HTTP frontend<br/>[frontend_http.py]"]
  node_terminal["Terminal chat<br/>[frontend_repl.py]"]
  node_widgets["HTML widgets<br/>[widgets.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_runtime["Agent runtime"]
  node_llm["Model registry<br/>[registry.py]"]
  node_attachment_parser["Attachment parsing<br/>[parse.py]"]
end

subgraph group_extensions["Extensions and sandbox"]
  node_plugin_discovery["Plugin discovery"]
  node_package_manager["Package manager<br/>[package_manager.py]"]
  node_sandbox_bridge["Sandbox bridge<br/>[bridge.py]"]
  node_plugin_validator["Plugin validator<br/>[validator.py]"]
  node_guest_sdk["Guest requests<br/>[requests.py]"]
end

subgraph group_state["State and configuration"]
  node_session["Session state<br/>[session.py]"]
  node_conversation["Conversation state<br/>[conversation.py]"]
  node_database[("Application database<br/>[database.py]")]
  node_config["Configuration<br/>[config_manager.py]"]
  node_events["Event bus<br/>[event_bus.py]"]
end

subgraph group_automation["Indexing and automation"]
  node_pipeline["File pipeline<br/>[orchestrator.py]"]
  node_scheduler["Scheduled tasks"]
end

node_user(("User"))
node_model_provider(("Model provider"))

node_user -->|"sends message"| node_web
node_user -->|"sends message"| node_terminal
node_web -.->|"uses frontend"| node_http
node_terminal -.->|"submits turns"| node_agent_runtime
node_http -.->|"submits turns"| node_agent_runtime
node_agent_runtime -.->|"requests completion"| node_llm
node_llm -.->|"calls model"| node_model_provider
node_session -->|"uses state"| node_conversation
node_agent_runtime -.->|"uses session"| node_session
node_agent_runtime -.->|"parses attachments"| node_attachment_parser
node_agent_runtime -.->|"invokes extensions"| node_sandbox_bridge
node_plugin_discovery -->|"adapts plugins"| node_sandbox_bridge
node_sandbox_bridge -->|"validates code"| node_plugin_validator
node_sandbox_bridge -->|"exposes requests"| node_guest_sdk
node_package_manager -->|"manages plugins"| node_plugin_discovery
node_agent_runtime -.->|"persists conversations"| node_database
node_agent_runtime -.->|"publishes updates"| node_events
node_session -->|"sends notifications"| node_events
node_agent_runtime -.->|"returns response"| node_user
node_pipeline -->|"records indexed files"| node_database
node_pipeline -->|"publishes events"| node_events
node_scheduler -.->|"triggers tasks"| node_pipeline
node_config -->|"emits changes"| node_events
node_user -->|"views widgets"| node_widgets

click node_web "https://github.com/henrydaum/second-brain/blob/main/frame_ui/src/App.tsx"
click node_http "https://github.com/henrydaum/second-brain/blob/main/bundled/frontends/frontend_http.py"
click node_terminal "https://github.com/henrydaum/second-brain/blob/main/bundled/frontends/frontend_repl.py"
click node_agent_runtime "https://github.com/henrydaum/second-brain/blob/main/runtime/conversation_runtime.py"
click node_llm "https://github.com/henrydaum/second-brain/blob/main/llm/registry.py"
click node_session "https://github.com/henrydaum/second-brain/blob/main/runtime/session.py"
click node_conversation "https://github.com/henrydaum/second-brain/blob/main/state_machine/conversation.py"
click node_database "https://github.com/henrydaum/second-brain/blob/main/pipeline/database.py"
click node_config "https://github.com/henrydaum/second-brain/blob/main/config/config_manager.py"
click node_events "https://github.com/henrydaum/second-brain/blob/main/events/event_bus.py"
click node_plugin_discovery "https://github.com/henrydaum/second-brain/blob/main/plugins/plugin_discovery.py"
click node_package_manager "https://github.com/henrydaum/second-brain/blob/main/bundled/commands/helpers/package_manager.py"
click node_sandbox_bridge "https://github.com/henrydaum/second-brain/blob/main/sandbox/bridge.py"
click node_plugin_validator "https://github.com/henrydaum/second-brain/blob/main/sandbox/validator.py"
click node_guest_sdk "https://github.com/henrydaum/second-brain/blob/main/sandbox/guest/requests.py"
click node_attachment_parser "https://github.com/henrydaum/second-brain/blob/main/attachments/parse.py"
click node_pipeline "https://github.com/henrydaum/second-brain/blob/main/pipeline/orchestrator.py"
click node_scheduler "https://github.com/henrydaum/second-brain/blob/main/bundled/services/service_timekeeper.py"
click node_widgets "https://github.com/henrydaum/second-brain/blob/main/frame_ui/src/lib/widgets.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_web,node_http,node_terminal,node_widgets,node_user toneBlue
class node_agent_runtime,node_llm,node_attachment_parser toneAmber
class node_plugin_discovery,node_package_manager,node_sandbox_bridge,node_plugin_validator,node_guest_sdk toneMint
class node_session,node_conversation,node_database,node_config,node_events toneRose
class node_pipeline,node_scheduler,node_model_provider toneIndigo
```

## Components

### User interfaces

- [Web chat](https://github.com/henrydaum/second-brain/blob/main/frame_ui/src/App.tsx): `frame_ui/src/App.tsx`
- [HTTP frontend](https://github.com/henrydaum/second-brain/blob/main/bundled/frontends/frontend_http.py): `bundled/frontends/frontend_http.py`
- [Terminal chat](https://github.com/henrydaum/second-brain/blob/main/bundled/frontends/frontend_repl.py): `bundled/frontends/frontend_repl.py`
- [HTML widgets](https://github.com/henrydaum/second-brain/blob/main/frame_ui/src/lib/widgets.ts): `frame_ui/src/lib/widgets.ts`

### Agent runtime

- [Agent runtime](https://github.com/henrydaum/second-brain/blob/main/runtime/conversation_runtime.py): `runtime/conversation_runtime.py`
- [Model registry](https://github.com/henrydaum/second-brain/blob/main/llm/registry.py): `llm/registry.py`
- [Attachment parsing](https://github.com/henrydaum/second-brain/blob/main/attachments/parse.py): `attachments/parse.py`

### Extensions and sandbox

- [Plugin discovery](https://github.com/henrydaum/second-brain/blob/main/plugins/plugin_discovery.py): `plugins/plugin_discovery.py`
- [Package manager](https://github.com/henrydaum/second-brain/blob/main/bundled/commands/helpers/package_manager.py): `bundled/commands/helpers/package_manager.py`
- [Sandbox bridge](https://github.com/henrydaum/second-brain/blob/main/sandbox/bridge.py): `sandbox/bridge.py`
- [Plugin validator](https://github.com/henrydaum/second-brain/blob/main/sandbox/validator.py): `sandbox/validator.py`
- [Guest requests](https://github.com/henrydaum/second-brain/blob/main/sandbox/guest/requests.py): `sandbox/guest/requests.py`

### State and configuration

- [Session state](https://github.com/henrydaum/second-brain/blob/main/runtime/session.py): `runtime/session.py`
- [Conversation state](https://github.com/henrydaum/second-brain/blob/main/state_machine/conversation.py): `state_machine/conversation.py`
- [Application database](https://github.com/henrydaum/second-brain/blob/main/pipeline/database.py): `pipeline/database.py`
- [Configuration](https://github.com/henrydaum/second-brain/blob/main/config/config_manager.py): `config/config_manager.py`
- [Event bus](https://github.com/henrydaum/second-brain/blob/main/events/event_bus.py): `events/event_bus.py`

### Indexing and automation

- [File pipeline](https://github.com/henrydaum/second-brain/blob/main/pipeline/orchestrator.py): `pipeline/orchestrator.py`
- [Scheduled tasks](https://github.com/henrydaum/second-brain/blob/main/bundled/services/service_timekeeper.py): `bundled/services/service_timekeeper.py`

### Other components

- **User**
- **Model provider**

## Connections

- User → Web chat: sends message (evidence: `README.md`)
- User → Terminal chat: sends message (evidence: `README.md`)
- Web chat → HTTP frontend: uses frontend (evidence: `README.md`)
- Terminal chat → Agent runtime: submits turns
- HTTP frontend → Agent runtime: submits turns
- Agent runtime → Model registry: requests completion
- Model registry → Model provider: calls model
- Session state → Conversation state: uses state (evidence: `runtime/session.py`)
- Agent runtime → Session state: uses session
- Agent runtime → Attachment parsing: parses attachments
- Agent runtime → Sandbox bridge: invokes extensions
- Plugin discovery → Sandbox bridge: adapts plugins (evidence: `plugins/plugin_discovery.py`)
- Sandbox bridge → Plugin validator: validates code (evidence: `sandbox/bridge.py`)
- Sandbox bridge → Guest requests: exposes requests (evidence: `sandbox/bridge.py`)
- Package manager → Plugin discovery: manages plugins (evidence: `bundled/commands/helpers/package_manager.py`)
- Agent runtime → Application database: persists conversations
- Agent runtime → Event bus: publishes updates
- Session state → Event bus: sends notifications (evidence: `runtime/session.py`)
- Agent runtime → User: returns response
- File pipeline → Application database: records indexed files (evidence: `pipeline/orchestrator.py`)
- File pipeline → Event bus: publishes events (evidence: `pipeline/orchestrator.py`)
- Scheduled tasks → File pipeline: triggers tasks
- Configuration → Event bus: emits changes (evidence: `config/config_manager.py`)
- User → HTML widgets: views widgets (evidence: `README.md`)
