# gaurgle/pinz architecture

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

- Interactive diagram: https://gitdiagram.com/gaurgle/pinz
- Repository: https://github.com/gaurgle/pinz

## Overview

pinz is a terminal-based spatial bulletin board whose notes are stored separately from the program in a git-backed pin repository. The main workflow is to open that repository, load its worlds and notes, navigate and edit the board in the TUI, then persist changes and synchronize them across machines. Its core separates the note/world model and projection from the terminal renderer; the storage seam also supports persistence concerns such as conflict handling and single-writer protection. The README documents sync and version commands; wiring for some CLI details is not fully shown in the sampled source.

Main entry points: [`crates/pinz-tui/src/main.rs`](https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/main.rs) (TUI entry), [`crates/pinz-tui/src/app.rs`](https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/app.rs) (App state), [`crates/pinz-tui/src/ui.rs`](https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/ui.rs) (Board renderer), [`crates/pinz-core/src/sync.rs`](https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/sync.rs) (Git synchronization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Terminal interaction"]
  node_main["TUI entry<br/>[main.rs]"]
  node_app["App state<br/>[app.rs]"]
  node_ui["Board renderer<br/>[ui.rs]"]
  node_editor["Text editor<br/>[editor.rs]"]
  node_clipboard["Clipboard<br/>[clipboard.rs]"]
  node_theme["Themes<br/>[theme.rs]"]
  node_wrap["Text wrapping<br/>[wrap.rs]"]
end

subgraph group_domain["Board domain"]
  node_view["Terminal projection<br/>[view.rs]"]
  node_model["Worlds and notes<br/>[model.rs]"]
  node_geometry["Projection geometry<br/>[geometry.rs]"]
end

subgraph group_persistence["Persistence and sync"]
  node_store["Storage seam<br/>[store.rs]"]
  node_files[("Pin file store<br/>[file_store.rs]")]
  node_lock["Board write lock<br/>[lock.rs]"]
  node_sync["Git synchronization<br/>[sync.rs]"]
  node_merge["Pin conflict merge<br/>[merge.rs]"]
end

subgraph group_commands["CLI operations"]
end

node_user(("Board user"))
node_pinrepo[("Pin repository")]
node_gitremote(("Git remote"))
node_release(("Release tags"))

node_user -->|"runs"| node_main
node_main -->|"opens and loads"| node_store
node_main -->|"creates and drives"| node_app
node_main -->|"draws frames"| node_ui
node_main -->|"acquires lock"| node_lock
node_main -->|"runs sync commands"| node_sync
node_app -->|"updates board"| node_model
node_app -->|"projects interaction"| node_view
node_app -->|"edits note text"| node_editor
node_app -.->|"copies and pastes"| node_clipboard
node_ui -->|"reads state"| node_app
node_ui -->|"positions notes"| node_view
node_ui -->|"styles display"| node_theme
node_ui -->|"wraps note text"| node_wrap
node_view -->|"uses projection math"| node_geometry
node_store -->|"implemented by"| node_files
node_main -->|"persists board"| node_files
node_files -->|"reads and writes"| node_pinrepo
node_sync -->|"commits and pulls"| node_pinrepo
node_sync -->|"fetches and pushes"| node_gitremote
node_sync -->|"resolves pin conflicts"| node_merge
node_main -.->|"checks latest tags"| node_release

click node_main "https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/main.rs"
click node_app "https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/app.rs"
click node_ui "https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/ui.rs"
click node_editor "https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/editor.rs"
click node_clipboard "https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/clipboard.rs"
click node_theme "https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/theme.rs"
click node_wrap "https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/wrap.rs"
click node_view "https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/view.rs"
click node_model "https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/model.rs"
click node_geometry "https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/geometry.rs"
click node_store "https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/store.rs"
click node_files "https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/file_store.rs"
click node_lock "https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/lock.rs"
click node_sync "https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/sync.rs"
click node_merge "https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/merge.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_app,node_ui,node_editor,node_clipboard,node_theme,node_wrap,node_user toneBlue
class node_view,node_model,node_geometry,node_pinrepo toneAmber
class node_store,node_files,node_lock,node_sync,node_merge toneMint
class node_gitremote,node_release toneIndigo
```

## Components

### Terminal interaction

- [TUI entry](https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/main.rs): `crates/pinz-tui/src/main.rs`
- [App state](https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/app.rs): `crates/pinz-tui/src/app.rs`
- [Board renderer](https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/ui.rs): `crates/pinz-tui/src/ui.rs`
- [Text editor](https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/editor.rs): `crates/pinz-tui/src/editor.rs`
- [Clipboard](https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/clipboard.rs): `crates/pinz-tui/src/clipboard.rs`
- [Themes](https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/theme.rs): `crates/pinz-tui/src/theme.rs`
- [Text wrapping](https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/wrap.rs): `crates/pinz-tui/src/wrap.rs`

### Board domain

- [Terminal projection](https://github.com/gaurgle/pinz/blob/main/crates/pinz-tui/src/view.rs): `crates/pinz-tui/src/view.rs`
- [Worlds and notes](https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/model.rs): `crates/pinz-core/src/model.rs`
- [Projection geometry](https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/geometry.rs): `crates/pinz-core/src/geometry.rs`

### Persistence and sync

- [Storage seam](https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/store.rs): `crates/pinz-core/src/store.rs`
- [Pin file store](https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/file_store.rs): `crates/pinz-core/src/file_store.rs`
- [Board write lock](https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/lock.rs): `crates/pinz-core/src/lock.rs`
- [Git synchronization](https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/sync.rs): `crates/pinz-core/src/sync.rs`
- [Pin conflict merge](https://github.com/gaurgle/pinz/blob/main/crates/pinz-core/src/merge.rs): `crates/pinz-core/src/merge.rs`

### Other components

- **Board user**
- **Pin repository**
- **Git remote**
- **Release tags**

## Connections

- Board user → TUI entry: runs
- TUI entry → Storage seam: opens and loads
- TUI entry → App state: creates and drives
- TUI entry → Board renderer: draws frames
- TUI entry → Board write lock: acquires lock
- TUI entry → Git synchronization: runs sync commands
- App state → Worlds and notes: updates board
- App state → Terminal projection: projects interaction
- App state → Text editor: edits note text
- App state → Clipboard: copies and pastes
- Board renderer → App state: reads state
- Board renderer → Terminal projection: positions notes
- Board renderer → Themes: styles display
- Board renderer → Text wrapping: wraps note text
- Terminal projection → Projection geometry: uses projection math
- Storage seam → Pin file store: implemented by
- TUI entry → Pin file store: persists board
- Pin file store → Pin repository: reads and writes
- Git synchronization → Pin repository: commits and pulls
- Git synchronization → Git remote: fetches and pushes
- Git synchronization → Pin conflict merge: resolves pin conflicts
- TUI entry → Release tags: checks latest tags