# securitytrip/birchpad architecture

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

- Interactive diagram: https://gitdiagram.com/securitytrip/birchpad
- Repository: https://github.com/securitytrip/birchpad

## Overview

Birchpad is a cross-platform desktop text editor. The principal workflow begins with a user launching the app or passing files on the command line; the app creates and manages a workspace, where users open and edit documents, search, and save. The documented runtime also includes configurable settings and keymaps, encoding support, visual layout, single-instance hand-off, and update checks. Source excerpts clarify some app-level dispatch and rendering relationships; other package connections below rely on the README’s package descriptions or are left unasserted where wiring was not shown.

Main entry points: [`crates/app/src/main.rs`](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/main.rs) (App entry), [`crates/app/src/workspace.rs`](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/workspace.rs) (Workspace), [`crates/app/src/buffer.rs`](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/buffer.rs) (Document buffer), [`crates/app/src/editor/mod.rs`](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/editor/mod.rs) (Editor view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop application"]
  node_main["App entry<br/>[main.rs]"]
  node_workspace["Workspace<br/>[workspace.rs]"]
  node_find["Find and replace<br/>[find.rs]"]
  node_fileops["File operations<br/>[file_ops.rs]"]
  node_encodingui["Encoding controls<br/>[encoding_ui.rs]"]
end

subgraph group_text["Document and view"]
  node_buffer["Document buffer<br/>[buffer.rs]"]
  node_editor["Editor view<br/>[mod.rs]"]
  node_coredoc["Text document<br/>[document.rs]"]
  node_viewmap["Display layout<br/>[display_map.rs]"]
  node_cells["Character cells<br/>[cells.rs]"]
  node_wrap["Word wrap<br/>[wrap.rs]"]
end

subgraph group_services["Configuration and I/O"]
  node_iofile["File I/O<br/>[file.rs]"]
  node_decode["Decode and detect<br/>[decode.rs]"]
  node_encoding["Encoding catalog<br/>[encoding.rs]"]
  node_config["Settings layers<br/>[layers.rs]"]
end

subgraph group_interaction["Commands and launch"]
  node_commands["Command registry<br/>[commands.rs]"]
  node_catalog["Command catalog<br/>[catalog.rs]"]
  node_cli["CLI arguments<br/>[args.rs]"]
  node_instance["Instance hand-off<br/>[instance.rs]"]
end

subgraph group_updates["Updates"]
  node_updates["Update checks<br/>[lib.rs]"]
end

node_user(("User"))

node_user -->|"launches"| node_main
node_main -->|"parses arguments"| node_cli
node_main -->|"starts instance"| node_instance
node_main -->|"loads settings"| node_config
node_main -->|"opens workspace"| node_workspace
node_workspace -->|"routes file actions"| node_fileops
node_workspace -->|"manages buffers"| node_buffer
node_workspace -->|"manages views"| node_editor
node_workspace -->|"dispatches commands"| node_commands
node_commands -->|"uses command data"| node_catalog
node_editor -->|"uses layout"| node_viewmap
node_editor -->|"shows buffer"| node_buffer
node_find -->|"searches document"| node_coredoc
node_viewmap -->|"uses cell metrics"| node_cells
node_viewmap -->|"uses wrapping"| node_wrap
node_fileops -->|"operates on buffers"| node_buffer
node_encodingui -->|"reloads buffer"| node_buffer
node_iofile -->|"reads through"| node_decode
node_decode -->|"uses encoding rules"| node_encoding
node_main -->|"installs update checks"| node_updates

click node_main "https://github.com/securitytrip/birchpad/blob/main/crates/app/src/main.rs"
click node_workspace "https://github.com/securitytrip/birchpad/blob/main/crates/app/src/workspace.rs"
click node_buffer "https://github.com/securitytrip/birchpad/blob/main/crates/app/src/buffer.rs"
click node_editor "https://github.com/securitytrip/birchpad/blob/main/crates/app/src/editor/mod.rs"
click node_coredoc "https://github.com/securitytrip/birchpad/blob/main/crates/core/src/document.rs"
click node_find "https://github.com/securitytrip/birchpad/blob/main/crates/app/src/find.rs"
click node_viewmap "https://github.com/securitytrip/birchpad/blob/main/crates/view/src/display_map.rs"
click node_cells "https://github.com/securitytrip/birchpad/blob/main/crates/view/src/cells.rs"
click node_wrap "https://github.com/securitytrip/birchpad/blob/main/crates/view/src/wrap.rs"
click node_fileops "https://github.com/securitytrip/birchpad/blob/main/crates/app/src/file_ops.rs"
click node_encodingui "https://github.com/securitytrip/birchpad/blob/main/crates/app/src/encoding_ui.rs"
click node_iofile "https://github.com/securitytrip/birchpad/blob/main/crates/io/src/file.rs"
click node_decode "https://github.com/securitytrip/birchpad/blob/main/crates/io/src/decode.rs"
click node_encoding "https://github.com/securitytrip/birchpad/blob/main/crates/io/src/encoding.rs"
click node_config "https://github.com/securitytrip/birchpad/blob/main/crates/config/src/layers.rs"
click node_commands "https://github.com/securitytrip/birchpad/blob/main/crates/app/src/commands.rs"
click node_catalog "https://github.com/securitytrip/birchpad/blob/main/crates/commands/src/catalog.rs"
click node_cli "https://github.com/securitytrip/birchpad/blob/main/crates/cli/src/args.rs"
click node_instance "https://github.com/securitytrip/birchpad/blob/main/crates/cli/src/instance.rs"
click node_updates "https://github.com/securitytrip/birchpad/blob/main/crates/update/src/lib.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_main,node_workspace,node_find,node_fileops,node_encodingui,node_user toneBlue
class node_buffer,node_editor,node_coredoc,node_viewmap,node_cells,node_wrap toneAmber
class node_iofile,node_decode,node_encoding,node_config toneMint
class node_commands,node_catalog,node_cli,node_instance toneRose
class node_updates toneIndigo
```

## Components

### Desktop application

- [App entry](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/main.rs): `crates/app/src/main.rs`
- [Workspace](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/workspace.rs): `crates/app/src/workspace.rs`
- [Find and replace](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/find.rs): `crates/app/src/find.rs`
- [File operations](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/file_ops.rs): `crates/app/src/file_ops.rs`
- [Encoding controls](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/encoding_ui.rs): `crates/app/src/encoding_ui.rs`

### Document and view

- [Document buffer](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/buffer.rs): `crates/app/src/buffer.rs`
- [Editor view](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/editor/mod.rs): `crates/app/src/editor/mod.rs`
- [Text document](https://github.com/securitytrip/birchpad/blob/main/crates/core/src/document.rs): `crates/core/src/document.rs`
- [Display layout](https://github.com/securitytrip/birchpad/blob/main/crates/view/src/display_map.rs): `crates/view/src/display_map.rs`
- [Character cells](https://github.com/securitytrip/birchpad/blob/main/crates/view/src/cells.rs): `crates/view/src/cells.rs`
- [Word wrap](https://github.com/securitytrip/birchpad/blob/main/crates/view/src/wrap.rs): `crates/view/src/wrap.rs`

### Configuration and I/O

- [File I/O](https://github.com/securitytrip/birchpad/blob/main/crates/io/src/file.rs): `crates/io/src/file.rs`
- [Decode and detect](https://github.com/securitytrip/birchpad/blob/main/crates/io/src/decode.rs): `crates/io/src/decode.rs`
- [Encoding catalog](https://github.com/securitytrip/birchpad/blob/main/crates/io/src/encoding.rs): `crates/io/src/encoding.rs`
- [Settings layers](https://github.com/securitytrip/birchpad/blob/main/crates/config/src/layers.rs): `crates/config/src/layers.rs`

### Commands and launch

- [Command registry](https://github.com/securitytrip/birchpad/blob/main/crates/app/src/commands.rs): `crates/app/src/commands.rs`
- [Command catalog](https://github.com/securitytrip/birchpad/blob/main/crates/commands/src/catalog.rs): `crates/commands/src/catalog.rs`
- [CLI arguments](https://github.com/securitytrip/birchpad/blob/main/crates/cli/src/args.rs): `crates/cli/src/args.rs`
- [Instance hand-off](https://github.com/securitytrip/birchpad/blob/main/crates/cli/src/instance.rs): `crates/cli/src/instance.rs`

### Updates

- [Update checks](https://github.com/securitytrip/birchpad/blob/main/crates/update/src/lib.rs): `crates/update/src/lib.rs`

### Other components

- **User**

## Connections

- User → App entry: launches (evidence: `README.md`)
- App entry → CLI arguments: parses arguments (evidence: `crates/app/src/main.rs`)
- App entry → Instance hand-off: starts instance (evidence: `crates/app/src/main.rs`)
- App entry → Settings layers: loads settings (evidence: `crates/app/src/main.rs`)
- App entry → Workspace: opens workspace (evidence: `crates/app/src/main.rs`)
- Workspace → File operations: routes file actions (evidence: `crates/app/src/workspace.rs`)
- Workspace → Document buffer: manages buffers (evidence: `crates/app/src/workspace.rs`)
- Workspace → Editor view: manages views (evidence: `crates/app/src/workspace.rs`)
- Workspace → Command registry: dispatches commands (evidence: `crates/app/src/workspace.rs`)
- Command registry → Command catalog: uses command data (evidence: `crates/app/src/commands.rs`)
- Editor view → Display layout: uses layout (evidence: `crates/app/src/editor/mod.rs`)
- Editor view → Document buffer: shows buffer (evidence: `crates/app/src/editor/mod.rs`)
- Find and replace → Text document: searches document (evidence: `crates/app/src/find.rs`)
- Display layout → Character cells: uses cell metrics (evidence: `crates/view/src/display_map.rs`)
- Display layout → Word wrap: uses wrapping (evidence: `crates/view/src/display_map.rs`)
- File operations → Document buffer: operates on buffers (evidence: `crates/app/src/file_ops.rs`)
- Encoding controls → Document buffer: reloads buffer (evidence: `crates/app/src/encoding_ui.rs`)
- File I/O → Decode and detect: reads through (evidence: `crates/io/src/file.rs`)
- Decode and detect → Encoding catalog: uses encoding rules (evidence: `crates/io/src/decode.rs`)
- App entry → Update checks: installs update checks (evidence: `crates/app/src/main.rs`)
