# nishron03/texgrab architecture

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

- Interactive diagram: https://gitdiagram.com/nishron03/texgrab
- Repository: https://github.com/nishron03/texgrab

## Overview

TexGrab is a macOS menu-bar tool that turns a user-selected screen region into LaTeX and copies only that text to the clipboard. Its main workflow runs from a global shortcut through permission-checked region capture, image recognition, and clipboard output; the app also offers sample OCR, shortcut/preferences controls, and status or notifications. The graph reflects documented capabilities and sampled call paths; some menu callbacks and supporting modules were not fully shown, so uncertain wiring is omitted.

Main entry points: [`src/texgrab/app.py`](https://github.com/nishron03/texgrab/blob/main/src/texgrab/app.py) (Menu app), [`src/texgrab/pipeline.py`](https://github.com/nishron03/texgrab/blob/main/src/texgrab/pipeline.py) (Snip service), [`src/texgrab/ocr/pix2tex_engine.py`](https://github.com/nishron03/texgrab/blob/main/src/texgrab/ocr/pix2tex_engine.py) (pix2tex engine), [`src/texgrab/capture/region.py`](https://github.com/nishron03/texgrab/blob/main/src/texgrab/capture/region.py) (Region capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App and controls"]
  node_app["Menu app<br/>[app.py]"]
  node_entry["App entry<br/>[__main__.py]"]
  node_snip["Snip service<br/>[pipeline.py]"]
end

subgraph group_capture["Shortcut and capture"]
  node_hotkey["Global hotkey<br/>[carbon.py]"]
  node_recorder["Shortcut recorder<br/>[recorder.py]"]
  node_combo["Shortcut rules<br/>[combo.py]"]
  node_permission["Capture permission<br/>[permissions.py]"]
  node_capture["Region capture<br/>[region.py]"]
end

subgraph group_recognition["OCR processing"]
  node_pipeline["Image pipeline<br/>[pipeline.py]"]
  node_engine["pix2tex engine<br/>[pix2tex_engine.py]"]
  node_preprocess["Image preparation<br/>[preprocess.py]"]
  node_matrix["Matrix handling<br/>[matrix.py]"]
end

subgraph group_system["Preferences and outputs"]
  node_config[("Saved preferences<br/>[config.py]")]
  node_clipboard["Clipboard writer<br/>[clipboard.py]"]
  node_notify["Notifications<br/>[notify.py]"]
end

node_user(("User"))
node_screencapture["macOS capture tool"]
node_model["pix2tex model"]
node_pasteboard[("macOS pasteboard")]
node_destination(("Paste destination"))

node_user -->|"presses shortcut"| node_hotkey
node_hotkey -->|"dispatches callback"| node_app
node_app -->|"checks access"| node_permission
node_app -->|"requests snip"| node_snip
node_snip -->|"calls capture"| node_capture
node_capture -->|"runs selection"| node_screencapture
node_capture -->|"returns image"| node_snip
node_snip -->|"runs recognition"| node_pipeline
node_pipeline -->|"recognizes image"| node_engine
node_engine -->|"prepares image"| node_preprocess
node_engine -->|"detects and fits"| node_matrix
node_engine -->|"runs inference"| node_model
node_pipeline -->|"writes LaTeX"| node_clipboard
node_clipboard -->|"sets text"| node_pasteboard
node_user -->|"pastes text"| node_destination
node_destination -->|"reads text"| node_pasteboard
node_app -->|"loads and saves"| node_config
node_app -->|"opens recorder"| node_recorder
node_recorder -->|"validates choice"| node_combo
node_app -->|"applies shortcut"| node_combo
node_app -->|"registers shortcut"| node_hotkey
node_app -->|"requests sample OCR"| node_snip
node_snip -->|"reports result"| node_notify
node_app -->|"reports permission"| node_notify
node_entry -->|"starts app"| node_app
node_user -->|"uses menu"| node_app

click node_app "https://github.com/nishron03/texgrab/blob/main/src/texgrab/app.py"
click node_entry "https://github.com/nishron03/texgrab/blob/main/src/texgrab/__main__.py"
click node_snip "https://github.com/nishron03/texgrab/blob/main/src/texgrab/pipeline.py"
click node_hotkey "https://github.com/nishron03/texgrab/blob/main/src/texgrab/hotkey/carbon.py"
click node_recorder "https://github.com/nishron03/texgrab/blob/main/src/texgrab/hotkey/recorder.py"
click node_combo "https://github.com/nishron03/texgrab/blob/main/src/texgrab/hotkey/combo.py"
click node_permission "https://github.com/nishron03/texgrab/blob/main/src/texgrab/permissions.py"
click node_capture "https://github.com/nishron03/texgrab/blob/main/src/texgrab/capture/region.py"
click node_pipeline "https://github.com/nishron03/texgrab/blob/main/src/texgrab/pipeline.py"
click node_engine "https://github.com/nishron03/texgrab/blob/main/src/texgrab/ocr/pix2tex_engine.py"
click node_preprocess "https://github.com/nishron03/texgrab/blob/main/src/texgrab/ocr/preprocess.py"
click node_matrix "https://github.com/nishron03/texgrab/blob/main/src/texgrab/ocr/matrix.py"
click node_config "https://github.com/nishron03/texgrab/blob/main/src/texgrab/config.py"
click node_clipboard "https://github.com/nishron03/texgrab/blob/main/src/texgrab/clipboard.py"
click node_notify "https://github.com/nishron03/texgrab/blob/main/src/texgrab/notify.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_app,node_entry,node_snip,node_user toneBlue
class node_hotkey,node_recorder,node_combo,node_permission,node_capture,node_pasteboard toneAmber
class node_pipeline,node_engine,node_preprocess,node_matrix toneMint
class node_config,node_clipboard,node_notify toneRose
class node_screencapture,node_model,node_destination toneIndigo
```

## Components

### App and controls

- [Menu app](https://github.com/nishron03/texgrab/blob/main/src/texgrab/app.py): `src/texgrab/app.py`
- [App entry](https://github.com/nishron03/texgrab/blob/main/src/texgrab/__main__.py): `src/texgrab/__main__.py`
- [Snip service](https://github.com/nishron03/texgrab/blob/main/src/texgrab/pipeline.py): `src/texgrab/pipeline.py`

### Shortcut and capture

- [Global hotkey](https://github.com/nishron03/texgrab/blob/main/src/texgrab/hotkey/carbon.py): `src/texgrab/hotkey/carbon.py`
- [Shortcut recorder](https://github.com/nishron03/texgrab/blob/main/src/texgrab/hotkey/recorder.py): `src/texgrab/hotkey/recorder.py`
- [Shortcut rules](https://github.com/nishron03/texgrab/blob/main/src/texgrab/hotkey/combo.py): `src/texgrab/hotkey/combo.py`
- [Capture permission](https://github.com/nishron03/texgrab/blob/main/src/texgrab/permissions.py): `src/texgrab/permissions.py`
- [Region capture](https://github.com/nishron03/texgrab/blob/main/src/texgrab/capture/region.py): `src/texgrab/capture/region.py`

### OCR processing

- [Image pipeline](https://github.com/nishron03/texgrab/blob/main/src/texgrab/pipeline.py): `src/texgrab/pipeline.py`
- [pix2tex engine](https://github.com/nishron03/texgrab/blob/main/src/texgrab/ocr/pix2tex_engine.py): `src/texgrab/ocr/pix2tex_engine.py`
- [Image preparation](https://github.com/nishron03/texgrab/blob/main/src/texgrab/ocr/preprocess.py): `src/texgrab/ocr/preprocess.py`
- [Matrix handling](https://github.com/nishron03/texgrab/blob/main/src/texgrab/ocr/matrix.py): `src/texgrab/ocr/matrix.py`

### Preferences and outputs

- [Saved preferences](https://github.com/nishron03/texgrab/blob/main/src/texgrab/config.py): `src/texgrab/config.py`
- [Clipboard writer](https://github.com/nishron03/texgrab/blob/main/src/texgrab/clipboard.py): `src/texgrab/clipboard.py`
- [Notifications](https://github.com/nishron03/texgrab/blob/main/src/texgrab/notify.py): `src/texgrab/notify.py`

### Other components

- **User**
- **macOS capture tool**
- **pix2tex model**
- **macOS pasteboard**
- **Paste destination**

## Connections

- User → Global hotkey: presses shortcut
- Global hotkey → Menu app: dispatches callback
- Menu app → Capture permission: checks access
- Menu app → Snip service: requests snip
- Snip service → Region capture: calls capture
- Region capture → macOS capture tool: runs selection
- Region capture → Snip service: returns image
- Snip service → Image pipeline: runs recognition
- Image pipeline → pix2tex engine: recognizes image
- pix2tex engine → Image preparation: prepares image
- pix2tex engine → Matrix handling: detects and fits
- pix2tex engine → pix2tex model: runs inference
- Image pipeline → Clipboard writer: writes LaTeX
- Clipboard writer → macOS pasteboard: sets text
- User → Paste destination: pastes text
- Paste destination → macOS pasteboard: reads text
- Menu app → Saved preferences: loads and saves
- Menu app → Shortcut recorder: opens recorder
- Shortcut recorder → Shortcut rules: validates choice
- Menu app → Shortcut rules: applies shortcut
- Menu app → Global hotkey: registers shortcut
- Menu app → Snip service: requests sample OCR
- Snip service → Notifications: reports result
- Menu app → Notifications: reports permission
- App entry → Menu app: starts app
- User → Menu app: uses menu