# schwarzilukas/braindump-butler architecture

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

- Interactive diagram: https://gitdiagram.com/schwarzilukas/braindump-butler
- Repository: https://github.com/schwarzilukas/braindump-butler

## Overview

BrainDump Butler is a PWA-backed assistant that turns raw notes into structured Obsidian Markdown, enriches them with tags and links, and saves them to a vault. Its main workflow runs through the notes API and skill orchestrator, then writes and indexes the note and commits it to Git. Separate API branches support refinement, templates, knowledge management, model selection, and manual sync. The README documents these capabilities; some implementation details are inferred only from the source index, so unsampled relationships are omitted.

Main entry points: [`backend/skills/orchestrator.py`](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/orchestrator.py) (Skill orchestrator), [`backend/main.py`](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/main.py) (FastAPI app), [`backend/api/notes.py`](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/notes.py) (Notes API), [`backend/services/git_sync.py`](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/services/git_sync.py) (Git sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["PWA client"]
  node_frontend["Web app<br/>[app.js]"]
end

subgraph group_api["API and routing"]
  node_main["FastAPI app<br/>[main.py]"]
  node_notes_api["Notes API<br/>[notes.py]"]
  node_refine_api["Refine API<br/>[refine.py]"]
  node_template_api["Templates API<br/>[templates.py]"]
  node_knowledge_api["Knowledge API<br/>[knowledge.py]"]
  node_sync_api["Sync API<br/>[sync.py]"]
  node_models_api["Models API<br/>[models.py]"]
  node_schemas["Note schemas<br/>[schemas.py]"]
end

subgraph group_skills["AI processing"]
  node_orchestrator["Skill orchestrator<br/>[orchestrator.py]"]
  node_intake["Intake skill<br/>[intake.py]"]
  node_clarify["Clarify skill<br/>[clarify.py]"]
  node_structure["Structure skill<br/>[structure.py]"]
  node_tag["Tag skill<br/>[tag.py]"]
  node_link["Link skill<br/>[link.py]"]
  node_refine["Refine skill<br/>[refine.py]"]
end

subgraph group_vault["Vault and persistence"]
  node_knowledge[("Knowledge base<br/>[context.py]")]
  node_index[("Vault index<br/>[vault_index.py]")]
  node_writer["Vault writer<br/>[vault_writer.py]"]
  node_git["Git sync<br/>[git_sync.py]"]
end

subgraph group_features["Supporting features"]
  node_template_service[("Template service")]
  node_ai_processor["AI processor<br/>[ai_processor.py]"]
end

node_user(("Note taker"))
node_copilot["Copilot SDK"]
node_vault[("Obsidian vault")]

node_user -->|"enters notes"| node_frontend
node_frontend -->|"uses API"| node_main
node_main -->|"routes requests"| node_notes_api
node_main -->|"routes requests"| node_refine_api
node_main -->|"routes requests"| node_template_api
node_main -->|"routes requests"| node_knowledge_api
node_main -->|"routes requests"| node_sync_api
node_main -->|"routes requests"| node_models_api
node_notes_api -->|"processes note"| node_orchestrator
node_notes_api -->|"validates data"| node_schemas
node_orchestrator -->|"runs"| node_intake
node_orchestrator -->|"may run"| node_clarify
node_orchestrator -->|"runs"| node_structure
node_orchestrator -->|"runs parallel"| node_tag
node_orchestrator -->|"runs parallel"| node_link
node_orchestrator -->|"runs sessions"| node_refine
node_orchestrator -->|"loads and updates"| node_knowledge
node_orchestrator -->|"loads context"| node_index
node_structure -->|"gets template"| node_template_service
node_notes_api -->|"writes note"| node_writer
node_notes_api -->|"updates index"| node_index
node_notes_api -->|"commits note"| node_git
node_writer -->|"writes Markdown"| node_vault
node_index -->|"indexes notes"| node_vault
node_git -->|"commits changes"| node_vault
node_refine_api -->|"starts sessions"| node_orchestrator
node_template_api -->|"manages templates"| node_template_service
node_knowledge_api -->|"reads and updates"| node_knowledge
node_sync_api -->|"controls sync"| node_git
node_models_api -.->|"lists models"| node_copilot
node_git -->|"pushes and pulls"| node_vault
node_orchestrator -.->|"uses AI skills"| node_copilot
node_ai_processor -->|"uses context"| node_knowledge
node_ai_processor -->|"uses schemas"| node_schemas

click node_frontend "https://github.com/schwarzilukas/braindump-butler/blob/main/frontend/static/app.js"
click node_main "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/main.py"
click node_notes_api "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/notes.py"
click node_refine_api "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/refine.py"
click node_template_api "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/templates.py"
click node_knowledge_api "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/knowledge.py"
click node_sync_api "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/sync.py"
click node_models_api "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/models.py"
click node_schemas "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/models/schemas.py"
click node_orchestrator "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/orchestrator.py"
click node_intake "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/intake.py"
click node_clarify "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/clarify.py"
click node_structure "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/structure.py"
click node_tag "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/tag.py"
click node_link "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/link.py"
click node_refine "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/refine.py"
click node_knowledge "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/knowledge/context.py"
click node_index "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/services/vault_index.py"
click node_writer "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/services/vault_writer.py"
click node_git "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/services/git_sync.py"
click node_template_service "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/services/template_service.py"
click node_ai_processor "https://github.com/schwarzilukas/braindump-butler/blob/main/backend/services/ai_processor.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 toneBlue
class node_main,node_notes_api,node_refine_api,node_template_api,node_knowledge_api,node_sync_api,node_models_api,node_schemas,node_vault toneAmber
class node_orchestrator,node_intake,node_clarify,node_structure,node_tag,node_link,node_refine toneMint
class node_knowledge,node_index,node_writer,node_git toneRose
class node_template_service,node_ai_processor,node_user,node_copilot toneIndigo
```

## Components

### PWA client

- [Web app](https://github.com/schwarzilukas/braindump-butler/blob/main/frontend/static/app.js): `frontend/static/app.js`

### API and routing

- [FastAPI app](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/main.py): `backend/main.py`
- [Notes API](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/notes.py): `backend/api/notes.py`
- [Refine API](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/refine.py): `backend/api/refine.py`
- [Templates API](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/templates.py): `backend/api/templates.py`
- [Knowledge API](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/knowledge.py): `backend/api/knowledge.py`
- [Sync API](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/sync.py): `backend/api/sync.py`
- [Models API](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/api/models.py): `backend/api/models.py`
- [Note schemas](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/models/schemas.py): `backend/models/schemas.py`

### AI processing

- [Skill orchestrator](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/orchestrator.py): `backend/skills/orchestrator.py`
- [Intake skill](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/intake.py): `backend/skills/intake.py`
- [Clarify skill](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/clarify.py): `backend/skills/clarify.py`
- [Structure skill](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/structure.py): `backend/skills/structure.py`
- [Tag skill](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/tag.py): `backend/skills/tag.py`
- [Link skill](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/link.py): `backend/skills/link.py`
- [Refine skill](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/skills/refine.py): `backend/skills/refine.py`

### Vault and persistence

- [Knowledge base](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/knowledge/context.py): `backend/knowledge/context.py`
- [Vault index](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/services/vault_index.py): `backend/services/vault_index.py`
- [Vault writer](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/services/vault_writer.py): `backend/services/vault_writer.py`
- [Git sync](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/services/git_sync.py): `backend/services/git_sync.py`

### Supporting features

- [Template service](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/services/template_service.py): `backend/services/template_service.py`
- [AI processor](https://github.com/schwarzilukas/braindump-butler/blob/main/backend/services/ai_processor.py): `backend/services/ai_processor.py`

### Other components

- **Note taker**
- **Copilot SDK**
- **Obsidian vault**

## Connections

- Note taker → Web app: enters notes (evidence: `README.md`)
- Web app → FastAPI app: uses API (evidence: `README.md`)
- FastAPI app → Notes API: routes requests (evidence: `backend/main.py`)
- FastAPI app → Refine API: routes requests (evidence: `backend/main.py`)
- FastAPI app → Templates API: routes requests (evidence: `backend/main.py`)
- FastAPI app → Knowledge API: routes requests (evidence: `backend/main.py`)
- FastAPI app → Sync API: routes requests (evidence: `backend/main.py`)
- FastAPI app → Models API: routes requests (evidence: `backend/main.py`)
- Notes API → Skill orchestrator: processes note (evidence: `backend/api/notes.py`)
- Notes API → Note schemas: validates data (evidence: `backend/api/notes.py`)
- Skill orchestrator → Intake skill: runs (evidence: `backend/skills/orchestrator.py`)
- Skill orchestrator → Clarify skill: may run (evidence: `backend/skills/orchestrator.py`)
- Skill orchestrator → Structure skill: runs (evidence: `backend/skills/orchestrator.py`)
- Skill orchestrator → Tag skill: runs parallel (evidence: `backend/skills/orchestrator.py`)
- Skill orchestrator → Link skill: runs parallel (evidence: `backend/skills/orchestrator.py`)
- Skill orchestrator → Refine skill: runs sessions (evidence: `backend/skills/orchestrator.py`)
- Skill orchestrator → Knowledge base: loads and updates (evidence: `backend/skills/orchestrator.py`)
- Skill orchestrator → Vault index: loads context (evidence: `backend/skills/orchestrator.py`)
- Structure skill → Template service: gets template (evidence: `backend/skills/structure.py`)
- Notes API → Vault writer: writes note (evidence: `backend/api/notes.py`)
- Notes API → Vault index: updates index (evidence: `backend/api/notes.py`)
- Notes API → Git sync: commits note (evidence: `backend/api/notes.py`)
- Vault writer → Obsidian vault: writes Markdown (evidence: `README.md`)
- Vault index → Obsidian vault: indexes notes (evidence: `backend/services/vault_index.py`)
- Git sync → Obsidian vault: commits changes (evidence: `backend/services/git_sync.py`)
- Refine API → Skill orchestrator: starts sessions (evidence: `backend/api/refine.py`)
- Templates API → Template service: manages templates (evidence: `backend/api/templates.py`)
- Knowledge API → Knowledge base: reads and updates (evidence: `backend/api/knowledge.py`)
- Sync API → Git sync: controls sync (evidence: `backend/api/sync.py`)
- Models API → Copilot SDK: lists models
- Git sync → Obsidian vault: pushes and pulls (evidence: `README.md`)
- Skill orchestrator → Copilot SDK: uses AI skills
- AI processor → Knowledge base: uses context (evidence: `backend/services/ai_processor.py`)
- AI processor → Note schemas: uses schemas (evidence: `backend/services/ai_processor.py`)
