# gpgtools/gpgservices architecture

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

- Interactive diagram: https://gitdiagram.com/gpgtools/gpgservices
- Repository: https://github.com/gpgtools/gpgservices

## Overview

##### Project type and purpose
- Type: Native macOS application bundle that installs a Services-menu extension.
- Purpose: Let users encrypt/decrypt/sign/verify files or text via the macOS Services menu, wrapping calls to GnuPG/MacGPG2.

##### File structure
- Dependencies/
– Zxcvbn library (password‐strength scoring).
– ZipKit library (zip/unzip support).
- Source/
– ServiceWorker, ServiceWrappedOperation, ZipOperation core classes.
– UI controllers: KeyChooserWindowController, RecipientWindowController, InProgressWindowController, VerificationResultsWindow, SimpleTextWindow, etc.
- Resources/
- Top-level
– Makefile + Xcode project (`GPGServices.xcodeproj`)
– Version.config, Info.plist

##### README for additional insights
- External requirements: MacGPG2 + Libmacgpg + GnuPG.
- Build uses Makefile & Xcode.
- MacOS Services integration.

##### Main components & interactions
a. OS Integration Layer
– macOS Services menu dispatch → ServiceWorker (implements NSUserInterfaceItem-Validation & NSServiceRequest).
b. Core Service Layer
– ServiceWorkerDelegate & ServiceWrappedOperation: wrap user request into an asynchronous operation.
– ZipOperation: compress/decompress attachments if requested.
– GKPasswordStrengthIndicator uses Zxcvbn lib to score user‐entered passphrase.
– ServiceWrappedOperation → invokes Libmacgpg/MacGPG2 command‐line tool or links against Libmacgpg to perform crypto.
c. UI Layer
– KeyChooserWindowController: prompt for which key to use.
– RecipientWindowController: prompt for recipients.
– InProgressWindowController: show progress via WorkerProgressViewItem.
– VerificationResultsWindow: display signature verification results.
– SimpleTextWindow: input/output text.
d. External Dependencies
– Zxcvbn (password strength)
– ZipKit (archive operations)
– Libmacgpg/GnuPG (actual crypto engine)

##### Architectural patterns & design principles
- Separation of concerns:
– UI controllers only handle user interaction & window management.
– Core service classes handle background work & OS communication.
– Dependencies layered in their own subdirectories.
- Asynchronous operations via NSOperation subclasses.
- Plugin/extension pattern: code installs as a Services provider.

- Clear component labels (class names, libraries, frameworks).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% OS Integration Layer
    subgraph "OS Integration Layer"
        direction TB
        SW["ServiceWorker"]:::os
    end

    %% Core Service Layer
    subgraph "Core Service Layer"
        direction TB
        SWD["ServiceWorkerDelegate"]:::core
        SWO["ServiceWrappedOperation"]:::core
        ZO["ZipOperation"]:::core
        PSI["GKPasswordStrengthIndicator"]:::core
    end

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        KC["KeyChooserWindowController"]:::ui
        RC["RecipientWindowController"]:::ui
        IP["InProgressWindowController"]:::ui
        VW["VerificationResultsWindow"]:::ui
        ST["SimpleTextWindow"]:::ui
        WP["WorkerProgressViewItem"]:::ui
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        ZX["Zxcvbn"]:::external
        ZP["ZipKit"]:::external
        GP["Libmacgpg/GnuPG"]:::external
    end

    %% Connections
    OS["macOS Services Menu"]:::os -->|"invoke via Services menu"| SW
    SW -->|"delegate events"| SWD
    SWD -->|"create operation"| SWO
    SWO -->|"compress/decompress"| ZO
    SWO -->|"score passphrase"| PSI
    SWO -->|"invoke crypto"| GP
    SWO -->|"report progress"| WP
    WP -->|"update UI"| IP
    SWO -->|"prompt key"| KC
    KC -->|"selected key"| SWO
    SWO -->|"prompt recipients"| RC
    RC -->|"selected recipients"| SWO
    SWO -->|"output text"| ST
    SWO -->|"verification results"| VW
    ZX -.-> PSI
    ZP -.-> ZO

    %% Click Events
    click SW "https://github.com/gpgtools/gpgservices/blob/dev/Source/ServiceWorker.h"
    click SW "https://github.com/gpgtools/gpgservices/blob/dev/Source/ServiceWorker.m"
    click SWD "https://github.com/gpgtools/gpgservices/blob/dev/Source/ServiceWorkerDelegate.h"
    click SWO "https://github.com/gpgtools/gpgservices/blob/dev/Source/ServiceWrappedOperation.h"
    click SWO "https://github.com/gpgtools/gpgservices/blob/dev/Source/ServiceWrappedOperation.m"
    click ZO "https://github.com/gpgtools/gpgservices/blob/dev/Source/ZipOperation.h"
    click ZO "https://github.com/gpgtools/gpgservices/blob/dev/Source/ZipOperation.m"
    click PSI "https://github.com/gpgtools/gpgservices/blob/dev/Source/GKPasswordStrengthIndicator.h"
    click PSI "https://github.com/gpgtools/gpgservices/blob/dev/Source/GKPasswordStrengthIndicator.m"
    click KC "https://github.com/gpgtools/gpgservices/blob/dev/Source/KeyChooserWindowController.h"
    click KC "https://github.com/gpgtools/gpgservices/blob/dev/Source/KeyChooserWindowController.m"
    click KC "https://github.com/gpgtools/gpgservices/blob/dev/Resources/Base.lproj/PrivateKeyChooserWindow.xib"
    click RC "https://github.com/gpgtools/gpgservices/blob/dev/Source/RecipientWindowController.h"
    click RC "https://github.com/gpgtools/gpgservices/blob/dev/Source/RecipientWindowController.m"
    click RC "https://github.com/gpgtools/gpgservices/blob/dev/Resources/Base.lproj/RecipientWindow.xib"
    click IP "https://github.com/gpgtools/gpgservices/blob/dev/Source/InProgressWindowController.h"
    click IP "https://github.com/gpgtools/gpgservices/blob/dev/Source/InProgressWindowController.m"
    click IP "https://github.com/gpgtools/gpgservices/blob/dev/Resources/InProgressWindow.xib"
    click VW "https://github.com/gpgtools/gpgservices/blob/dev/Source/VerificationResultsWindow.h"
    click VW "https://github.com/gpgtools/gpgservices/blob/dev/Source/VerificationResultsWindow.m"
    click VW "https://github.com/gpgtools/gpgservices/blob/dev/Resources/Base.lproj/VerificationResultsWindow.xib"
    click ST "https://github.com/gpgtools/gpgservices/blob/dev/Source/SimpleTextWindow.h"
    click ST "https://github.com/gpgtools/gpgservices/blob/dev/Source/SimpleTextWindow.m"
    click ST "https://github.com/gpgtools/gpgservices/blob/dev/Resources/SimpleTextWindow.xib"
    click WP "https://github.com/gpgtools/gpgservices/blob/dev/Source/WorkerProgressViewItem.h"
    click WP "https://github.com/gpgtools/gpgservices/blob/dev/Source/WorkerProgressViewItem.m"
    click ZX "https://github.com/gpgtools/gpgservices/tree/dev/Dependencies/Zxcvbn"
    click ZP "https://github.com/gpgtools/gpgservices/tree/dev/Dependencies/zipkit"

    %% Styles
    classDef os fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef core fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px;
    classDef ui fill:#bbdefb,stroke:#1565c0,stroke-width:1px;
    classDef external fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px;
```
