# jdubbs89/proofshot architecture

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

## Overview

Proofshot is a Linux CLI for organizing project screenshots through indexed, categorized captures and export. The main workflow selects a project and column, resolves an index and filename, invokes a screenshot provider, then records the successful image and advances persistent counters. Users can also list screenshots, manage project columns and naming templates, upgrade legacy mappings, and package selected ranges into ZIP files. The README documents these capabilities; sampled excerpts support the central orchestration and storage edges, but not every command’s internal call sequence.

Main entry points: [`proofshot.py`](https://github.com/jdubbs89/proofshot/blob/main/proofshot.py) (Command orchestration), [`lib/config_service.py`](https://github.com/jdubbs89/proofshot/blob/main/lib/config_service.py) (Project configuration), [`lib/screenshot_service.py`](https://github.com/jdubbs89/proofshot/blob/main/lib/screenshot_service.py) (Capture safety), [`lib/package_service.py`](https://github.com/jdubbs89/proofshot/blob/main/lib/package_service.py) (ZIP packaging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_orchestrator["Command orchestration<br/>[proofshot.py]"]
  node_indexing["Index and naming<br/>[proofshot.py]"]
end

subgraph group_project["Project organization"]
  node_project_config["Project configuration<br/>[config_service.py]"]
  node_column_ops["Column management<br/>[config_service.py]"]
  node_global_state[("Project and counters")]
  node_project_settings["Project settings"]
  node_manifest["Content manifest"]
  node_screenshots["Project PNGs"]
end

subgraph group_capture["Capture providers"]
  node_capture_service["Capture safety"]
  node_provider_selection["Provider selection<br/>[config_service.py]"]
end

subgraph group_export["Listing and export"]
  node_listing["Screenshot listing<br/>[proofshot.py]"]
  node_legacy_discovery["Legacy discovery<br/>[proofshot.py]"]
  node_upgrade["Legacy upgrade<br/>[proofshot.py]"]
  node_package_selection["Column and range selection<br/>[proofshot.py]"]
  node_zip_service["ZIP packaging<br/>[package_service.py]"]
  node_zip_output["Package ZIP"]
end

node_user(("CLI user"))
node_flameshot["Flameshot"]
node_gnome["GNOME Screenshot"]

node_user -->|"runs commands"| node_orchestrator
node_orchestrator -->|"loads and edits"| node_project_config
node_project_config -->|"reads and writes"| node_project_settings
node_project_config -->|"reads and writes"| node_global_state
node_orchestrator -->|"resolves capture"| node_indexing
node_orchestrator -->|"loads provider"| node_provider_selection
node_provider_selection -->|"reads selection"| node_global_state
node_orchestrator -->|"captures image"| node_capture_service
node_capture_service -.->|"runs capture"| node_flameshot
node_capture_service -.->|"runs capture"| node_gnome
node_orchestrator -->|"writes successful capture"| node_screenshots
node_orchestrator -->|"records capture"| node_manifest
node_orchestrator -->|"persists directory and counters"| node_global_state
node_orchestrator -->|"lists screenshots"| node_listing
node_listing -->|"uses content mappings"| node_manifest
node_listing -->|"discovers older files"| node_legacy_discovery
node_legacy_discovery -->|"scans PNGs"| node_screenshots
node_orchestrator -->|"upgrades project"| node_upgrade
node_upgrade -->|"reads legacy mappings"| node_legacy_discovery
node_upgrade -->|"writes mappings"| node_manifest
node_orchestrator -->|"starts packaging"| node_package_selection
node_package_selection -->|"passes selected files"| node_zip_service
node_zip_service -->|"reads PNGs"| node_screenshots
node_zip_service -->|"writes archive"| node_zip_output

click node_orchestrator "https://github.com/jdubbs89/proofshot/blob/main/proofshot.py"
click node_indexing "https://github.com/jdubbs89/proofshot/blob/main/proofshot.py"
click node_project_config "https://github.com/jdubbs89/proofshot/blob/main/lib/config_service.py"
click node_column_ops "https://github.com/jdubbs89/proofshot/blob/main/lib/config_service.py"
click node_capture_service "https://github.com/jdubbs89/proofshot/blob/main/lib/screenshot_service.py"
click node_provider_selection "https://github.com/jdubbs89/proofshot/blob/main/lib/config_service.py"
click node_listing "https://github.com/jdubbs89/proofshot/blob/main/proofshot.py"
click node_legacy_discovery "https://github.com/jdubbs89/proofshot/blob/main/proofshot.py"
click node_upgrade "https://github.com/jdubbs89/proofshot/blob/main/proofshot.py"
click node_package_selection "https://github.com/jdubbs89/proofshot/blob/main/proofshot.py"
click node_zip_service "https://github.com/jdubbs89/proofshot/blob/main/lib/package_service.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_orchestrator,node_indexing,node_user,node_gnome toneBlue
class node_project_config,node_column_ops,node_global_state,node_project_settings,node_manifest,node_screenshots toneAmber
class node_capture_service,node_provider_selection toneMint
class node_listing,node_legacy_discovery,node_upgrade,node_package_selection,node_zip_service,node_zip_output toneRose
class node_flameshot toneIndigo
```

## Components

### CLI workflow

- [Command orchestration](https://github.com/jdubbs89/proofshot/blob/main/proofshot.py): `proofshot.py`
- [Index and naming](https://github.com/jdubbs89/proofshot/blob/main/proofshot.py): `proofshot.py`

### Project organization

- [Project configuration](https://github.com/jdubbs89/proofshot/blob/main/lib/config_service.py): `lib/config_service.py`
- [Column management](https://github.com/jdubbs89/proofshot/blob/main/lib/config_service.py): `lib/config_service.py`
- **Project and counters**
- **Project settings**
- **Content manifest**
- **Project PNGs**

### Capture providers

- [Capture safety](https://github.com/jdubbs89/proofshot/blob/main/lib/screenshot_service.py): `lib/screenshot_service.py`
- [Provider selection](https://github.com/jdubbs89/proofshot/blob/main/lib/config_service.py): `lib/config_service.py`

### Listing and export

- [Screenshot listing](https://github.com/jdubbs89/proofshot/blob/main/proofshot.py): `proofshot.py`
- [Legacy discovery](https://github.com/jdubbs89/proofshot/blob/main/proofshot.py): `proofshot.py`
- [Legacy upgrade](https://github.com/jdubbs89/proofshot/blob/main/proofshot.py): `proofshot.py`
- [Column and range selection](https://github.com/jdubbs89/proofshot/blob/main/proofshot.py): `proofshot.py`
- [ZIP packaging](https://github.com/jdubbs89/proofshot/blob/main/lib/package_service.py): `lib/package_service.py`
- **Package ZIP**

### Other components

- **CLI user**
- **Flameshot**
- **GNOME Screenshot**

## Connections

- CLI user → Command orchestration: runs commands
- Command orchestration → Project configuration: loads and edits
- Project configuration → Project settings: reads and writes
- Project configuration → Project and counters: reads and writes
- Command orchestration → Index and naming: resolves capture
- Command orchestration → Provider selection: loads provider
- Provider selection → Project and counters: reads selection
- Command orchestration → Capture safety: captures image
- Capture safety → Flameshot: runs capture
- Capture safety → GNOME Screenshot: runs capture
- Command orchestration → Project PNGs: writes successful capture
- Command orchestration → Content manifest: records capture
- Command orchestration → Project and counters: persists directory and counters
- Command orchestration → Screenshot listing: lists screenshots
- Screenshot listing → Content manifest: uses content mappings
- Screenshot listing → Legacy discovery: discovers older files
- Legacy discovery → Project PNGs: scans PNGs
- Command orchestration → Legacy upgrade: upgrades project
- Legacy upgrade → Legacy discovery: reads legacy mappings
- Legacy upgrade → Content manifest: writes mappings
- Command orchestration → Column and range selection: starts packaging
- Column and range selection → ZIP packaging: passes selected files
- ZIP packaging → Project PNGs: reads PNGs
- ZIP packaging → Package ZIP: writes archive