# guy5116/burrow architecture

> Architecture diagram of the GitHub repository guy5116/burrow, 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/guy5116/burrow
- Repository: https://github.com/guy5116/burrow

## Overview

Burrow is a peer-to-peer, end-to-end encrypted chat application. A user initializes a protected identity, creates or uses a one-time invite (or connects to a saved contact), establishes a secure peer session, then exchanges text and optionally transfers pictures or files. The CLI/TUI and desktop GUI are separate front ends to the core engine. The graph also shows storage, transport, protocol, and media-processing layers. Some subsystem links rely on SOURCE INDEX references or README statements; unsampled implementation details are not inferred.

Main entry points: [`internal/core/engine.go`](https://github.com/guy5116/burrow/blob/main/internal/core/engine.go) (Core engine), [`internal/session/session.go`](https://github.com/guy5116/burrow/blob/main/internal/session/session.go) (Encrypted sessions), [`internal/core/transfer.go`](https://github.com/guy5116/burrow/blob/main/internal/core/transfer.go) (File transfers), [`internal/store/store.go`](https://github.com/guy5116/burrow/blob/main/internal/store/store.go) (Encrypted store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["User interfaces"]
  node_cli["CLI commands<br/>[cmds.go]"]
  node_runtime["CLI runtime<br/>[run.go]"]
  node_tui["Terminal UI<br/>[tui.go]"]
  node_common["UI commands<br/>[commands.go]"]
  node_gui["Desktop UI<br/>[main.go]"]
  node_guiapp["GUI application<br/>[app.go]"]
end

subgraph group_core["Chat engine"]
  node_engine["Core engine<br/>[engine.go]"]
  node_peer["Peer messaging<br/>[peer.go]"]
  node_transfer["File transfers<br/>[transfer.go]"]
end

subgraph group_security["Identity and protocol"]
  node_identity["Identity keys<br/>[identity.go]"]
  node_invite["Invites<br/>[invite.go]"]
  node_handshake["Secure handshake<br/>[handshake.go]"]
  node_session["Encrypted sessions<br/>[session.go]"]
  node_wire["Wire protocol<br/>[payloads.go]"]
end

subgraph group_network["Networking"]
  node_transports["Transport selection<br/>[transports.go]"]
  node_tcp["TCP transport<br/>[tcp.go]"]
  node_tor["Tor transport<br/>[tor.go]"]
end

subgraph group_data["Persistence and media"]
  node_store[("Encrypted store<br/>[store.go]")]
  node_media["Image handling<br/>[strip.go]"]
end

node_user(("Chat user"))

node_user -->|"runs commands"| node_cli
node_cli -->|"starts chat"| node_runtime
node_runtime -->|"opens terminal UI"| node_tui
node_tui -->|"uses commands"| node_common
node_common -->|"calls chat API"| node_engine
node_user -->|"uses desktop app"| node_gui
node_gui -->|"starts application"| node_guiapp
node_guiapp -->|"starts engine"| node_engine
node_cli -->|"loads store"| node_store
node_guiapp -->|"opens store"| node_store
node_engine -->|"persists state"| node_store
node_engine -->|"uses invites"| node_invite
node_engine -->|"uses identity"| node_identity
node_engine -->|"runs handshake"| node_handshake
node_engine -->|"creates sessions"| node_session
node_engine -->|"selects transports"| node_transports
node_engine -->|"routes peer events"| node_peer
node_peer -->|"uses session"| node_session
node_engine -->|"handles transfers"| node_transfer
node_transfer -->|"sends streams"| node_session
node_transfer -->|"stores received files"| node_store
node_transfer -->|"checks image data"| node_media
node_handshake -->|"encodes handshake"| node_wire
node_handshake -->|"uses keys"| node_identity
node_session -->|"frames messages"| node_wire
node_session -->|"uses peer keys"| node_identity
node_transports -.->|"uses TCP"| node_tcp
node_transports -.->|"supports Tor"| node_tor

click node_cli "https://github.com/guy5116/burrow/blob/main/cmd/burrow/cmds.go"
click node_runtime "https://github.com/guy5116/burrow/blob/main/cmd/burrow/run.go"
click node_tui "https://github.com/guy5116/burrow/blob/main/internal/ui/tui/tui.go"
click node_common "https://github.com/guy5116/burrow/blob/main/internal/ui/common/commands.go"
click node_gui "https://github.com/guy5116/burrow/blob/main/internal/ui/gui/main.go"
click node_guiapp "https://github.com/guy5116/burrow/blob/main/internal/ui/gui/app.go"
click node_engine "https://github.com/guy5116/burrow/blob/main/internal/core/engine.go"
click node_peer "https://github.com/guy5116/burrow/blob/main/internal/core/peer.go"
click node_transfer "https://github.com/guy5116/burrow/blob/main/internal/core/transfer.go"
click node_identity "https://github.com/guy5116/burrow/blob/main/internal/identity/identity.go"
click node_invite "https://github.com/guy5116/burrow/blob/main/internal/invite/invite.go"
click node_handshake "https://github.com/guy5116/burrow/blob/main/internal/handshake/handshake.go"
click node_session "https://github.com/guy5116/burrow/blob/main/internal/session/session.go"
click node_wire "https://github.com/guy5116/burrow/blob/main/internal/wire/payloads.go"
click node_transports "https://github.com/guy5116/burrow/blob/main/internal/core/transports.go"
click node_tcp "https://github.com/guy5116/burrow/blob/main/internal/transport/tcp/tcp.go"
click node_tor "https://github.com/guy5116/burrow/blob/main/internal/transport/tor/tor.go"
click node_store "https://github.com/guy5116/burrow/blob/main/internal/store/store.go"
click node_media "https://github.com/guy5116/burrow/blob/main/internal/media/strip.go"

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_cli,node_runtime,node_tui,node_common,node_gui,node_guiapp,node_user toneBlue
class node_engine,node_peer,node_transfer toneAmber
class node_identity,node_invite,node_handshake,node_session,node_wire toneMint
class node_transports,node_tcp,node_tor toneRose
class node_store,node_media toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/guy5116/burrow/blob/main/cmd/burrow/cmds.go): `cmd/burrow/cmds.go`
- [CLI runtime](https://github.com/guy5116/burrow/blob/main/cmd/burrow/run.go): `cmd/burrow/run.go`
- [Terminal UI](https://github.com/guy5116/burrow/blob/main/internal/ui/tui/tui.go): `internal/ui/tui/tui.go`
- [UI commands](https://github.com/guy5116/burrow/blob/main/internal/ui/common/commands.go): `internal/ui/common/commands.go`
- [Desktop UI](https://github.com/guy5116/burrow/blob/main/internal/ui/gui/main.go): `internal/ui/gui/main.go`
- [GUI application](https://github.com/guy5116/burrow/blob/main/internal/ui/gui/app.go): `internal/ui/gui/app.go`

### Chat engine

- [Core engine](https://github.com/guy5116/burrow/blob/main/internal/core/engine.go): `internal/core/engine.go`
- [Peer messaging](https://github.com/guy5116/burrow/blob/main/internal/core/peer.go): `internal/core/peer.go`
- [File transfers](https://github.com/guy5116/burrow/blob/main/internal/core/transfer.go): `internal/core/transfer.go`

### Identity and protocol

- [Identity keys](https://github.com/guy5116/burrow/blob/main/internal/identity/identity.go): `internal/identity/identity.go`
- [Invites](https://github.com/guy5116/burrow/blob/main/internal/invite/invite.go): `internal/invite/invite.go`
- [Secure handshake](https://github.com/guy5116/burrow/blob/main/internal/handshake/handshake.go): `internal/handshake/handshake.go`
- [Encrypted sessions](https://github.com/guy5116/burrow/blob/main/internal/session/session.go): `internal/session/session.go`
- [Wire protocol](https://github.com/guy5116/burrow/blob/main/internal/wire/payloads.go): `internal/wire/payloads.go`

### Networking

- [Transport selection](https://github.com/guy5116/burrow/blob/main/internal/core/transports.go): `internal/core/transports.go`
- [TCP transport](https://github.com/guy5116/burrow/blob/main/internal/transport/tcp/tcp.go): `internal/transport/tcp/tcp.go`
- [Tor transport](https://github.com/guy5116/burrow/blob/main/internal/transport/tor/tor.go): `internal/transport/tor/tor.go`

### Persistence and media

- [Encrypted store](https://github.com/guy5116/burrow/blob/main/internal/store/store.go): `internal/store/store.go`
- [Image handling](https://github.com/guy5116/burrow/blob/main/internal/media/strip.go): `internal/media/strip.go`

### Other components

- **Chat user**

## Connections

- Chat user → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → CLI runtime: starts chat
- CLI runtime → Terminal UI: opens terminal UI (evidence: `cmd/burrow/run.go`)
- Terminal UI → UI commands: uses commands (evidence: `internal/ui/tui/tui.go`)
- UI commands → Core engine: calls chat API (evidence: `internal/ui/common/commands.go`)
- Chat user → Desktop UI: uses desktop app (evidence: `README.md`)
- Desktop UI → GUI application: starts application
- GUI application → Core engine: starts engine (evidence: `internal/ui/gui/app.go`)
- CLI commands → Encrypted store: loads store (evidence: `cmd/burrow/cmds.go`)
- GUI application → Encrypted store: opens store (evidence: `internal/ui/gui/app.go`)
- Core engine → Encrypted store: persists state (evidence: `internal/core/engine.go`)
- Core engine → Invites: uses invites (evidence: `internal/core/engine.go`)
- Core engine → Identity keys: uses identity (evidence: `internal/core/engine.go`)
- Core engine → Secure handshake: runs handshake (evidence: `internal/core/engine.go`)
- Core engine → Encrypted sessions: creates sessions (evidence: `internal/core/engine.go`)
- Core engine → Transport selection: selects transports (evidence: `internal/core/engine.go`)
- Core engine → Peer messaging: routes peer events (evidence: `internal/core/engine.go`)
- Peer messaging → Encrypted sessions: uses session (evidence: `internal/core/peer.go`)
- Core engine → File transfers: handles transfers (evidence: `internal/core/transfer.go`)
- File transfers → Encrypted sessions: sends streams (evidence: `internal/core/transfer.go`)
- File transfers → Encrypted store: stores received files (evidence: `internal/core/transfer.go`)
- File transfers → Image handling: checks image data (evidence: `internal/core/transfer.go`)
- Secure handshake → Wire protocol: encodes handshake (evidence: `internal/handshake/handshake.go`)
- Secure handshake → Identity keys: uses keys (evidence: `internal/handshake/handshake.go`)
- Encrypted sessions → Wire protocol: frames messages (evidence: `internal/session/session.go`)
- Encrypted sessions → Identity keys: uses peer keys (evidence: `internal/session/session.go`)
- Transport selection → TCP transport: uses TCP
- Transport selection → Tor transport: supports Tor
