# scottidler/second-brain architecture

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

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

## Overview

second-brain is a Rust workspace centered on one shared Obsidian vault: borg captures and distills incoming material, cortex governs and enriches vault notes, and oracle exposes knowledge retrieval through MCP. The principal path runs from a capture source through borg’s ingest pipeline and per-kind distillation into vault notes; users then query those notes through oracle. The README documents transport, governance, intel, embedding, and retrieval capabilities. Some subsystem links reflect README documentation or module responsibilities because their implementation was not sampled.

Main entry points: [`borg/src/pipeline.rs`](https://github.com/scottidler/second-brain/blob/main/borg/src/pipeline.rs) (Ingest pipeline), [`sb/src/cli.rs`](https://github.com/scottidler/second-brain/blob/main/sb/src/cli.rs) (sb command line), [`cortex/src/lib.rs`](https://github.com/scottidler/second-brain/blob/main/cortex/src/lib.rs) (Cortex daemon), [`oracle/src/server.rs`](https://github.com/scottidler/second-brain/blob/main/oracle/src/server.rs) (Oracle MCP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and distill"]
  node_borg_routes["HTTP capture<br/>[routes.rs]"]
  node_borg_transports["Messaging transports"]
  node_borg_pipeline["Ingest pipeline<br/>[pipeline.rs]"]
  node_borg_handlers["Media handlers<br/>[handlers.rs]"]
  node_distillers["Kind distillers<br/>[lib.rs]"]
end

subgraph group_shared["Shared vault"]
  node_vault_files["Obsidian notes"]
  node_vault_api["Vault services<br/>[lib.rs]"]
  node_vault_search[("Search index<br/>[query.rs]")]
  node_borg_ledger[("Ingest ledger<br/>[ledger.rs]")]
end

subgraph group_governance["Vault governance"]
  node_cortex["Cortex daemon<br/>[lib.rs]"]
  node_cortex_lint["Lint and links"]
  node_cortex_intel["Intel and embedding"]
end

subgraph group_retrieval["Knowledge retrieval"]
  node_oracle_server["Oracle MCP<br/>[server.rs]"]
  node_oracle_pipeline["Retrieval pipeline<br/>[pipeline.rs]"]
  node_oracle_tools["Knowledge tools<br/>[tools.rs]"]
end

subgraph group_operations["CLI operations"]
  node_sb_cli["sb command line<br/>[cli.rs]"]
end

node_capture_sources(("Capture sources"))
node_fabric["Fabric patterns"]
node_users(("People and clients"))

node_capture_sources -->|"submit capture"| node_borg_routes
node_capture_sources -->|"send content"| node_borg_transports
node_borg_routes -->|"dispatch ingest"| node_borg_pipeline
node_borg_transports -->|"dispatch ingest"| node_borg_pipeline
node_borg_pipeline -->|"process media"| node_borg_handlers
node_borg_pipeline -->|"distill content"| node_distillers
node_borg_handlers -->|"distill media"| node_distillers
node_distillers -.->|"invoke patterns"| node_fabric
node_borg_pipeline -->|"write notes"| node_vault_api
node_borg_pipeline -->|"record ingest"| node_borg_ledger
node_vault_api -->|"read and write"| node_vault_files
node_cortex -->|"scan and update"| node_vault_api
node_cortex -->|"run governance"| node_cortex_lint
node_cortex -->|"run enrichment"| node_cortex_intel
node_cortex_intel -->|"enrich notes"| node_vault_api
node_oracle_server -->|"serve tools"| node_oracle_tools
node_oracle_server -->|"dispatch search"| node_oracle_pipeline
node_oracle_pipeline -->|"retrieve notes"| node_vault_search
node_vault_search -->|"index vault"| node_vault_files
node_users -->|"run commands"| node_sb_cli
node_sb_cli -->|"invoke ingest"| node_borg_pipeline
node_sb_cli -->|"invoke tasks"| node_cortex
node_sb_cli -->|"launch server"| node_oracle_server
node_users -->|"query via MCP"| node_oracle_server

click node_borg_routes "https://github.com/scottidler/second-brain/blob/main/borg/src/routes.rs"
click node_borg_transports "https://github.com/scottidler/second-brain/tree/main/borg/src"
click node_borg_pipeline "https://github.com/scottidler/second-brain/blob/main/borg/src/pipeline.rs"
click node_borg_handlers "https://github.com/scottidler/second-brain/blob/main/borg/src/pipeline/handlers.rs"
click node_distillers "https://github.com/scottidler/second-brain/blob/main/distillers/src/lib.rs"
click node_vault_api "https://github.com/scottidler/second-brain/blob/main/vault/src/lib.rs"
click node_vault_search "https://github.com/scottidler/second-brain/blob/main/vault/src/search/query.rs"
click node_borg_ledger "https://github.com/scottidler/second-brain/blob/main/borg/src/ledger.rs"
click node_cortex "https://github.com/scottidler/second-brain/blob/main/cortex/src/lib.rs"
click node_cortex_lint "https://github.com/scottidler/second-brain/tree/main/cortex/src"
click node_cortex_intel "https://github.com/scottidler/second-brain/tree/main/cortex/src"
click node_oracle_server "https://github.com/scottidler/second-brain/blob/main/oracle/src/server.rs"
click node_oracle_pipeline "https://github.com/scottidler/second-brain/blob/main/oracle/src/server/pipeline.rs"
click node_oracle_tools "https://github.com/scottidler/second-brain/blob/main/oracle/src/tools.rs"
click node_sb_cli "https://github.com/scottidler/second-brain/blob/main/sb/src/cli.rs"

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_borg_routes,node_borg_transports,node_borg_pipeline,node_borg_handlers,node_distillers,node_users toneBlue
class node_vault_files,node_vault_api,node_vault_search,node_borg_ledger toneAmber
class node_cortex,node_cortex_lint,node_cortex_intel toneMint
class node_oracle_server,node_oracle_pipeline,node_oracle_tools toneRose
class node_sb_cli,node_capture_sources,node_fabric toneIndigo
```

## Components

### Capture and distill

- [HTTP capture](https://github.com/scottidler/second-brain/blob/main/borg/src/routes.rs): `borg/src/routes.rs`
- [Messaging transports](https://github.com/scottidler/second-brain/tree/main/borg/src): `borg/src`
- [Ingest pipeline](https://github.com/scottidler/second-brain/blob/main/borg/src/pipeline.rs): `borg/src/pipeline.rs`
- [Media handlers](https://github.com/scottidler/second-brain/blob/main/borg/src/pipeline/handlers.rs): `borg/src/pipeline/handlers.rs`
- [Kind distillers](https://github.com/scottidler/second-brain/blob/main/distillers/src/lib.rs): `distillers/src/lib.rs`

### Shared vault

- **Obsidian notes**
- [Vault services](https://github.com/scottidler/second-brain/blob/main/vault/src/lib.rs): `vault/src/lib.rs`
- [Search index](https://github.com/scottidler/second-brain/blob/main/vault/src/search/query.rs): `vault/src/search/query.rs`
- [Ingest ledger](https://github.com/scottidler/second-brain/blob/main/borg/src/ledger.rs): `borg/src/ledger.rs`

### Vault governance

- [Cortex daemon](https://github.com/scottidler/second-brain/blob/main/cortex/src/lib.rs): `cortex/src/lib.rs`
- [Lint and links](https://github.com/scottidler/second-brain/tree/main/cortex/src): `cortex/src`
- [Intel and embedding](https://github.com/scottidler/second-brain/tree/main/cortex/src): `cortex/src`

### Knowledge retrieval

- [Oracle MCP](https://github.com/scottidler/second-brain/blob/main/oracle/src/server.rs): `oracle/src/server.rs`
- [Retrieval pipeline](https://github.com/scottidler/second-brain/blob/main/oracle/src/server/pipeline.rs): `oracle/src/server/pipeline.rs`
- [Knowledge tools](https://github.com/scottidler/second-brain/blob/main/oracle/src/tools.rs): `oracle/src/tools.rs`

### CLI operations

- [sb command line](https://github.com/scottidler/second-brain/blob/main/sb/src/cli.rs): `sb/src/cli.rs`

### Other components

- **Capture sources**
- **Fabric patterns**
- **People and clients**

## Connections

- Capture sources → HTTP capture: submit capture
- Capture sources → Messaging transports: send content
- HTTP capture → Ingest pipeline: dispatch ingest
- Messaging transports → Ingest pipeline: dispatch ingest
- Ingest pipeline → Media handlers: process media
- Ingest pipeline → Kind distillers: distill content
- Media handlers → Kind distillers: distill media
- Kind distillers → Fabric patterns: invoke patterns
- Ingest pipeline → Vault services: write notes
- Ingest pipeline → Ingest ledger: record ingest
- Vault services → Obsidian notes: read and write
- Cortex daemon → Vault services: scan and update
- Cortex daemon → Lint and links: run governance
- Cortex daemon → Intel and embedding: run enrichment
- Intel and embedding → Vault services: enrich notes
- Oracle MCP → Knowledge tools: serve tools
- Oracle MCP → Retrieval pipeline: dispatch search
- Retrieval pipeline → Search index: retrieve notes
- Search index → Obsidian notes: index vault
- People and clients → sb command line: run commands
- sb command line → Ingest pipeline: invoke ingest
- sb command line → Cortex daemon: invoke tasks
- sb command line → Oracle MCP: launch server
- People and clients → Oracle MCP: query via MCP