# gpgtools/libmacgpg architecture

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

## Overview

##### Project type and purpose
- This is an Objective-C framework project (“Libmacgpg”) that abstracts and simplifies communication with GnuPG on macOS.
- It provides:
- A shared framework (Libmacgpg.framework)
- An XPC helper service (org.gpgtools.Libmacgpg.xpc)
- Two sample macOS GUI apps (LeakFinder, SignatureViewApp)
- Unit tests and helper targets.
- Primary use-case: Client apps link against the framework to perform cryptographic operations via GnuPG without dealing directly with pipes or subprocesses.

##### File structure
- Top-level targets:
- LeakFinder (macOS GUI app)
- SignatureViewApp (macOS GUI app)
- Libmacgpg.xcodeproj → builds Libmacgpg.framework & XPC service
- Source/ → Objective-C implementation of:
- GPGTask & GPGTaskHelper (process management)
- GPGStream, file/ memory streaming
- GPGPacket* classes (packet parsing)
- Controllers, Managers, Settings, Exceptions
- XPC entrypoint under org.gpgtools.Libmacgpg.xpc
- UnitTests/ → automated test suite driving the core framework classes.
- Resources/ → localization and configuration (keyserver lists, .plist).
- Build/Install:
- Makefile orchestrates compilation & packaging of framework + XPC service.

##### README for additional insights
- Confirms framework usage pattern: Link, install framework, install XPC plist and agent, launchctl load helper.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Client Applications Layer
  subgraph "Client Applications" 
    direction TB
    LeakFinder["LeakFinder"]:::frontend
    SignatureViewApp["SignatureViewApp"]:::frontend
  end

  %% Framework Layer
  subgraph "Libmacgpg.framework" 
    direction TB
    LibmacgpgProj["Libmacgpg.xcodeproj"]:::framework
    PublicAPI["Libmacgpg.h"]:::framework
    subgraph "Process Management"
      direction TB
      GPGTask["GPGTask"]:::framework
      GPGTaskHelper["GPGTaskHelper"]:::framework
      GPGTaskHelperXPC["GPGTaskHelperXPC"]:::framework
    end
    subgraph "Streaming Abstractions"
      direction TB
      GPGStream["GPGStream"]:::framework
      GPGFileStream["GPGFileStream"]:::framework
      GPGMemoryStream["GPGMemoryStream"]:::framework
    end
    subgraph "Packet Parsing"
      direction TB
      GPGPacketParser["GPGPacket*"]:::framework
    end
    subgraph "Controllers & Managers"
      direction TB
      GPGController["GPGController"]:::framework
      GPGKeyManager["GPGKeyManager"]:::framework
      GPGUpdateController["GPGUpdateController"]:::framework
      GPGWatcher["GPGWatcher"]:::framework
    end
    subgraph "Settings & Config"
      direction TB
      GPGArraySetting["GPGArraySetting"]:::framework
      GPGDictSetting["GPGDictSetting"]:::framework
      GPGLinesSetting["GPGLinesSetting"]:::framework
      GPGStdSetting["GPGStdSetting"]:::framework
    end
    GPGException["GPGException"]:::framework
    GPGGlobals["GPGGlobals"]:::framework
    GPGOptions["GPGOptions"]:::framework
    subgraph "Utilities & Localization"
      direction TB
      GPGLocalization["NSBundle+GPGLocalization"]:::framework
      SandboxExt["NSBundle+Sandbox"]:::framework
      NoSigPipe["NSPipe+NoSigPipe"]:::framework
    end
  end

  %% XPC Service Layer
  subgraph "XPC Helper Service" 
    direction TB
    XPCService["org.gpgtools.Libmacgpg.xpc"]:::xpc
  end

  %% GnuPG Process
  subgraph "GnuPG Process" 
    direction TB
    GnuPG["GnuPG CLI"]:::process
  end

  %% External Resources
  Keyserver["Keyserver (HTTP/HTTPS)"]:::external
  FileSystem["Local File System"]:::fs

  %% Unit Test Harness
  UnitTests["UnitTests Harness"]:::test
  SocketTest["GPGSocketCloseTest"]:::test

  %% Connections
  LeakFinder -->|"Objective-C API"| PublicAPI
  SignatureViewApp -->|"Objective-C API"| PublicAPI
  PublicAPI -->|calls| GPGTask
  GPGTaskHelper -->|uses| GPGTask
  GPGTaskHelperXPC -->|XPC interface| XPCService
  GPGStream -->|streams| GPGTaskHelper
  GPGFileStream -->|streams| GPGTaskHelper
  GPGMemoryStream -->|streams| GPGTaskHelper
  GPGPacketParser -->|parses| GPGStream
  GPGController -->|orchestrates| GPGTaskHelper
  GPGController -->|manages| GPGKeyManager
  GPGUpdateController -->|updates| GPGGlobals
  GPGWatcher -->|watches| FileSystem
  GPGArraySetting -->|configures| GPGTaskHelper
  GPGDictSetting -->|configures| GPGTask
  GPGLinesSetting -->|configures| GPGTask
  GPGStdSetting -->|configures| GPGTask
  GPGException -->|handles| GPGTask
  GPGOptions -->|provides| PublicAPI
  GPGLocalization -->|extends| PublicAPI
  SandboxExt -->|extends| XPCService
  NoSigPipe -->|extends| GPGTask

  PublicAPI -->|"XPC pipe"| XPCService
  XPCService -->|"stdin/stdout"| GnuPG
  GnuPG -->|"reads/writes"| FileSystem
  GnuPG -->|"HTTP(S)"| Keyserver
  GnuPG -->|"stdout response"| XPCService
  XPCService -->|"XPC response"| PublicAPI
  PublicAPI -->|"callback"| LeakFinder
  PublicAPI -->|"callback"| SignatureViewApp

  UnitTests -->|direct call| GPGController
  UnitTests -->|direct call| GPGTask
  SocketTest -->|edge-case test| GPGTaskHelper

  %% Click Events
  click LeakFinder "https://github.com/gpgtools/libmacgpg/tree/dev/LeakFinder/"
  click SignatureViewApp "https://github.com/gpgtools/libmacgpg/tree/dev/SignatureViewApp/"
  click LibmacgpgProj "https://github.com/gpgtools/libmacgpg/tree/dev/Libmacgpg.xcodeproj/"
  click PublicAPI "https://github.com/gpgtools/libmacgpg/blob/dev/Source/Libmacgpg.h"
  click XPCService "https://github.com/gpgtools/libmacgpg/tree/dev/Source/org.gpgtools.Libmacgpg.xpc/"
  click GPGTask "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGTask.h"
  click GPGTaskHelper "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGTaskHelper.h"
  click GPGTaskHelperXPC "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGTaskHelperXPC.h"
  click GPGStream "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGStream.h"
  click GPGFileStream "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGFileStream.h"
  click GPGMemoryStream "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGMemoryStream.h"
  click GPGPacketParser "https://github.com/gpgtools/libmacgpg/tree/dev/Source/GPGPacket/"
  click GPGController "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGController.h"
  click GPGKeyManager "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGKeyManager.h"
  click GPGUpdateController "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGUpdateController.h"
  click GPGWatcher "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGWatcher.h"
  click GPGArraySetting "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGArraySetting.h"
  click GPGDictSetting "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGDictSetting.h"
  click GPGLinesSetting "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGLinesSetting.h"
  click GPGStdSetting "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGStdSetting.h"
  click GPGException "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGException.h"
  click GPGGlobals "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGGlobals.h"
  click GPGOptions "https://github.com/gpgtools/libmacgpg/blob/dev/Source/GPGOptions.h"
  click GPGLocalization "https://github.com/gpgtools/libmacgpg/blob/dev/Source/NSBundle+GPGLocalization.h"
  click SandboxExt "https://github.com/gpgtools/libmacgpg/blob/dev/Source/NSBundle+Sandbox.h"
  click NoSigPipe "https://github.com/gpgtools/libmacgpg/blob/dev/Source/NSPipe+NoSigPipe.h"
  click UnitTests "https://github.com/gpgtools/libmacgpg/tree/dev/UnitTests/"
  click SocketTest "https://github.com/gpgtools/libmacgpg/blob/dev/NewUnitTests/GPGSocketCloseTest.m"
  click FileSystem "https://github.com/gpgtools/libmacgpg/tree/dev/Resources/"
  click Keyserver "https://github.com/gpgtools/libmacgpg/blob/dev/Resources/Keyservers.plist"

  %% Styles
  classDef frontend fill:#cfc,stroke:#080
  classDef framework fill:#ccf,stroke:#00f
  classDef xpc fill:#fc8,stroke:#f60
  classDef process fill:#ccc,stroke:#666
  classDef external fill:#cff,stroke:#08f,shape:cloud
  classDef fs fill:#ffc,stroke:#f90,shape:cylinder
  classDef test stroke-dasharray: 3 3,fill:#fff,stroke:#f00
```
