# rca/gpgmail architecture

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

## Overview

##### Project Type and Purpose
- This is a macOS “bundle‐injection” plugin for Apple’s Mail.app. It uses Objective-C categories and method swizzling to hook into Mail’s message compose and view workflows, adding GPG encryption, decryption, signature, and key-management features.

##### Top-Level Components
- Host Application: Mail.app (not in your repo, but the environment into which your code is injected)
- Plugin Bundle: GPGMailBundle (the .bundle loaded by Mail)
- Frameworks/Dependencies:
- MacGPGME (wrapping the GPG binary and keyrings)
- Sparkle.framework (self-update mechanism)
- External Services:
- GPG binary (spawned as a subprocess via GPGTask)
- Public keyservers (as defined in KeyServers.plist)
- Build & Release Tools:
- Makefile and build-gpgme.sh (compile/assemble everything)
- Ruby scripts (generate_keys.rb, sign_update.rb)
- appcast.xml (update feed)

##### Internal Plugin Structure
- Source/Category Hooks: a large set of `+GPGMail` categories on Mail’s private headers (Message, MimePart, ComposeBackEnd, etc.)
- UI Components: NIBs for compose accessory, preference panels, key-download dialogs (in Resources/)
- Core Encryption Logic: GPGKeyDownload, GPGPassphraseController, GPGHandler, GPGSignature, GPGTask
- Preferences & Keychain Integration: NSPreferences_GPGMail, MessageKeychainManager+GPGMail

##### Data Flows & Interactions
a. Compose/Send Flow (Encryption & Signing)
- User writes email in Mail.app → plugin intercepts via ComposeBackEnd+GPGMail → passes cleartext to GPGME APIs → GPGTask spawns `gpg` subprocess → returns encrypted MIME parts → Mail.app continues to send.
b. Receive/Viewing Flow (Decryption & Verification)
- Mail.app delivers inbound message → plugin intercepts via MessageViewer+GPGMail → passes encrypted blob to GPGME → spawns `gpg` → returns decrypted body or signature status → plugin renders results in accessory view.
c. Key Management & Download
- Preferences UI or Compose UI triggers GPGKeyDownload → HTTP fetch from keyservers → stores keys in local keyring via GPGME.
d. Self-Update via Sparkle
- Sparkle.framework checks `appcast.xml` → downloads signed update → invokes sign_update.rb and generate_keys.rb → installs new plugin bundle.

##### Architectural Patterns & Principles
- Dynamic Plugin/Inversion-of-Control: code is delivered as a .bundle and loaded into a host process at runtime.
- Adapter/Facade: MacGPGME wraps underlying GPG command-line interface.
- Category / Swizzling (Cross-Cutting Concern): augment Mail’s classes without modifying Mail.app directly.
- Modular Localization: hundreds of `.lproj` folders with NIB/UI and `.strings`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Layer
    subgraph "Host Layer"
        MailApp["Mail.app"]:::host
    end

    %% Plugin Bundle
    subgraph "Plugin Bundle" 
        Bundle["GPGMailBundle (entry point)"]:::plugin
        Hooks["Category Hooks (Compose, Message, Mime, etc.)"]:::plugin
        subgraph "Crypto Core"
            Handler["GPGHandler"]:::plugin
            Task["GPGTask"]:::plugin
            Signature["GPGSignature"]:::plugin
            KeyDownload["GPGKeyDownload"]:::plugin
        end
        subgraph "Preferences & Keychain"
            Prefs["NSPreferences_GPGMail"]:::plugin
            Keychain["MessageKeychainManager+GPGMail"]:::plugin
        end
        subgraph "UI Resources"
            UINibs["UI NIBs & Localization"]:::plugin
        end
    end

    %% Frameworks & Dependencies
    subgraph "Frameworks"
        MacGPGME["MacGPGME.framework"]:::framework
        Sparkle["Sparkle.framework"]:::framework
    end

    %% External Services & Data
    subgraph "External"
        GPGBinary["GPG binary subprocess"]:::process
        Keyserver["External Keyservers"]:::data
        Appcast["appcast.xml"]:::data
    end

    %% Build & Release Tools
    subgraph "Build & Release"
        Build["Makefile & Scripts"]:::utility
        Signing["sign_update.rb / generate_keys.rb"]:::utility
    end

    %% Plugin loading and method hooks
    MailApp -->|"loads .bundle"| Bundle
    Bundle -->|"swizzles methods"| Hooks
    Hooks -->|"intercepts compose/view"| MailApp

    %% Crypto flows
    Bundle -->|"invokes crypto"| Handler
    Handler -->|"wraps API"| MacGPGME
    Handler -->|"spawns subprocess"| Task
    Task -->|"executes"| GPGBinary
    Bundle -->|"downloads keys"| KeyDownload
    KeyDownload -->|"fetches"| Keyserver

    %% Update flow
    Bundle -->|"uses update"| Sparkle
    Sparkle -->|"checks feed"| Appcast
    Sparkle -->|"triggers"| Signing

    %% Preferences integration
    Bundle --> Prefs
    Bundle --> Keychain

    %% UI resources
    Bundle --> UINibs

    %% Build pipeline
    Build --> Bundle
    Build --> MacGPGME
    Build --> Sparkle
    Signing --> Build

    %% Click events
    click Bundle "https://github.com/rca/gpgmail/blob/master/GPGMail/Source/GPGMailBundle.m"
    click Handler "https://github.com/rca/gpgmail/blob/master/GPGMail/Source/GPG.subproj/GPGHandler.m"
    click Task "https://github.com/rca/gpgmail/blob/master/GPGMail/Source/GPG.subproj/GPGTask.m"
    click Signature "https://github.com/rca/gpgmail/blob/master/GPGMail/Source/GPG.subproj/GPGSignature.m"
    click KeyDownload "https://github.com/rca/gpgmail/blob/master/GPGMail/Source/GPGKeyDownload.m"
    click Prefs "https://github.com/rca/gpgmail/blob/master/GPGMail/Source/NSPreferences_GPGMail.m"
    click Keychain "https://github.com/rca/gpgmail/blob/master/GPGMail/Source/MessageKeychainManager+GPGMail.m"
    click Sparkle "https://github.com/rca/gpgmail/blob/master/GPGMail/Frameworks/Sparkle.framework"
    click Keyserver "https://github.com/rca/gpgmail/blob/master/GPGMail/Plists/KeyServers.plist"
    click Build "https://github.com/rca/gpgmail/tree/master/GPGMail/Makefile"

    %% Styles
    classDef host fill:#FFDDAA,stroke:#333,stroke-width:1px
    classDef plugin fill:#DDEEFF,stroke:#333,stroke-width:1px
    classDef framework fill:#EEFFDD,stroke:#333,stroke-width:1px
    classDef process fill:#FFDDDD,stroke:#333,stroke-width:1px
    classDef data fill:#DDFFDD,stroke:#333,stroke-width:1px
    classDef utility fill:#F0E68C,stroke:#333,stroke-width:1px
```
