# learnwithparam/second-brain-workshop architecture

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

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

## Overview

Second brain workshop is a local, Markdown-backed notes system for keeping company-specific ideas, references, and issues. Users can add, rate, update, remove, search, and traverse linked notes through either a CLI used by Claude Code or an MCP server for other apps; both interfaces call the same core, which stores notes and logs changes in vault/. The README also documents inbox-based ingest and separate research and draft skills. Those skill workflows are represented from documentation; their source instructions were not sampled.

Main entry points: [`src/brain.ts`](https://github.com/learnwithparam/second-brain-workshop/blob/main/src/brain.ts) (Brain core), [`inbox`](https://github.com/learnwithparam/second-brain-workshop/tree/main/inbox) (Raw items), [`src/cli.ts`](https://github.com/learnwithparam/second-brain-workshop/blob/main/src/cli.ts) (CLI), [`src/mcp.ts`](https://github.com/learnwithparam/second-brain-workshop/blob/main/src/mcp.ts) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guidance["Claude guidance"]
  node_inbox["Raw items"]
  node_rules["Claude rules<br/>[CLAUDE.md]"]
  node_brands["Brand criteria"]
  node_ingest["Ingest skill<br/>[SKILL.md]"]
  node_research["Research skill<br/>[SKILL.md]"]
  node_draft["Draft skill<br/>[SKILL.md]"]
  node_prompts["Workshop prompts<br/>[prompts.md]"]
end

subgraph group_access["Access interfaces"]
  node_cli["CLI<br/>[cli.ts]"]
  node_mcp["MCP server<br/>[mcp.ts]"]
end

subgraph group_brain["Brain and notes"]
  node_core["Brain core<br/>[brain.ts]"]
  node_vault[("Markdown vault")]
  node_change_log["Change log<br/>[log.md]"]
end

node_user(("User"))
node_claude(("Claude Code"))
node_mcp_apps(("MCP apps"))

node_user -->|"provides items"| node_inbox
node_inbox -->|"feeds ingest"| node_claude
node_rules -->|"guides"| node_claude
node_brands -->|"sets criteria"| node_claude
node_ingest -->|"guides ingest"| node_claude
node_research -->|"guides research"| node_claude
node_draft -->|"guides drafting"| node_claude
node_prompts -->|"starts workshop"| node_claude
node_claude -->|"runs commands"| node_cli
node_mcp_apps -->|"uses tools"| node_mcp
node_cli -->|"calls"| node_core
node_mcp -->|"calls"| node_core
node_core -->|"reads and writes"| node_vault
node_core -->|"appends changes"| node_change_log

click node_inbox "https://github.com/learnwithparam/second-brain-workshop/tree/main/inbox"
click node_rules "https://github.com/learnwithparam/second-brain-workshop/blob/main/CLAUDE.md"
click node_brands "https://github.com/learnwithparam/second-brain-workshop/tree/main/brands"
click node_ingest "https://github.com/learnwithparam/second-brain-workshop/blob/main/.claude/skills/ingest/SKILL.md"
click node_research "https://github.com/learnwithparam/second-brain-workshop/blob/main/.claude/skills/research/SKILL.md"
click node_draft "https://github.com/learnwithparam/second-brain-workshop/blob/main/.claude/skills/draft/SKILL.md"
click node_prompts "https://github.com/learnwithparam/second-brain-workshop/blob/main/prompts.md"
click node_cli "https://github.com/learnwithparam/second-brain-workshop/blob/main/src/cli.ts"
click node_mcp "https://github.com/learnwithparam/second-brain-workshop/blob/main/src/mcp.ts"
click node_core "https://github.com/learnwithparam/second-brain-workshop/blob/main/src/brain.ts"
click node_vault "https://github.com/learnwithparam/second-brain-workshop/tree/main/vault"
click node_change_log "https://github.com/learnwithparam/second-brain-workshop/blob/main/vault/log.md"

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_inbox,node_rules,node_brands,node_ingest,node_research,node_draft,node_prompts,node_user toneBlue
class node_cli,node_mcp toneAmber
class node_core,node_vault,node_change_log toneMint
class node_claude,node_mcp_apps toneIndigo
```

## Components

### Claude guidance

- [Raw items](https://github.com/learnwithparam/second-brain-workshop/tree/main/inbox): `inbox`
- [Claude rules](https://github.com/learnwithparam/second-brain-workshop/blob/main/CLAUDE.md): `CLAUDE.md`
- [Brand criteria](https://github.com/learnwithparam/second-brain-workshop/tree/main/brands): `brands`
- [Ingest skill](https://github.com/learnwithparam/second-brain-workshop/blob/main/.claude/skills/ingest/SKILL.md): `.claude/skills/ingest/SKILL.md`
- [Research skill](https://github.com/learnwithparam/second-brain-workshop/blob/main/.claude/skills/research/SKILL.md): `.claude/skills/research/SKILL.md`
- [Draft skill](https://github.com/learnwithparam/second-brain-workshop/blob/main/.claude/skills/draft/SKILL.md): `.claude/skills/draft/SKILL.md`
- [Workshop prompts](https://github.com/learnwithparam/second-brain-workshop/blob/main/prompts.md): `prompts.md`

### Access interfaces

- [CLI](https://github.com/learnwithparam/second-brain-workshop/blob/main/src/cli.ts): `src/cli.ts`
- [MCP server](https://github.com/learnwithparam/second-brain-workshop/blob/main/src/mcp.ts): `src/mcp.ts`

### Brain and notes

- [Brain core](https://github.com/learnwithparam/second-brain-workshop/blob/main/src/brain.ts): `src/brain.ts`
- [Markdown vault](https://github.com/learnwithparam/second-brain-workshop/tree/main/vault): `vault`
- [Change log](https://github.com/learnwithparam/second-brain-workshop/blob/main/vault/log.md): `vault/log.md`

### Other components

- **User**
- **Claude Code**
- **MCP apps**

## Connections

- User → Raw items: provides items (evidence: `README.md`)
- Raw items → Claude Code: feeds ingest (evidence: `README.md`)
- Claude rules → Claude Code: guides (evidence: `README.md`)
- Brand criteria → Claude Code: sets criteria (evidence: `README.md`)
- Ingest skill → Claude Code: guides ingest (evidence: `README.md`)
- Research skill → Claude Code: guides research (evidence: `README.md`)
- Draft skill → Claude Code: guides drafting (evidence: `README.md`)
- Workshop prompts → Claude Code: starts workshop (evidence: `README.md`)
- Claude Code → CLI: runs commands (evidence: `README.md`)
- MCP apps → MCP server: uses tools (evidence: `README.md`)
- CLI → Brain core: calls (evidence: `src/cli.ts`)
- MCP server → Brain core: calls (evidence: `src/mcp.ts`)
- Brain core → Markdown vault: reads and writes (evidence: `src/brain.ts`)
- Brain core → Change log: appends changes (evidence: `src/brain.ts`)
