# macpass/macpass architecture

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

- Interactive diagram: https://gitdiagram.com/macpass/macpass
- Repository: https://github.com/macpass/macpass

## Overview

##### Project type and purpose
- MacPass is a native macOS, document‐based Cocoa application (Objective-C) that provides a GUI front end for KeePass databases (KDB/KDBX).
- It implements a standard AppKit / MVC architecture, with submodules for database handling (KeePassKit, MiniKeePass, KeePassLib), UI helpers (HNHUi, PXSourceList, KSPasswordField), plus services like autotype, plugins, and Sparkle updates.

##### High-level file-structure analysis
- MacPass.xcodeproj – Xcode solution defining targets for the app and tests.
- MacPass/ – the main source directory, organized by MVC roles:
– Base.lproj, *.xib – interface builder files (views) and localized strings.
– MP*.h/.m – App Delegate, Document Controller/Window Controllers, View Controllers (UI controllers).
– MPDocument, KPK* – model classes wrapping the KeePass database representation and parsing.
– MPAutotype* – business logic for “autotype” features.
– MPPlugin* – plugin host and management.
– MPSettingsHelper, MPTemporaryFileStorage – configuration, persistence helpers.
- Cartfile & Cartfile.resolved – Carthage dependencies for external frameworks (Sparkle, TransformerKit, DDHotKey, etc.).
- scripts/ – build and release automation.
- MacPassTests/ – unit and integration tests.

##### System components and interactions
a. User Interface Layer (Blue)
– AppKit UI: XIBs → NSWindow, NSTreeView, NSTableView, NSPopUpButton; View Controllers (e.g. MPEntryViewController).
– MPAppDelegate → application lifecycle.
– MPDocumentController + MPDocumentWindowController → document open/edit/save UI.
b. Core Logic Layer (Green)
– Model: MPDocument + KPKBinary/KPKFormat classes → parse/serialize KeePass databases (via KeePassKit).
– Autotype: MPAutotypeParser → MPAutotypeCommand → MPAutotypeDaemon → MPKeyTyper (synthesizes key events).
– Plugins: MPPluginHost loads bundles → MPPluginEntryActionContext → invokes plugin code.
– Preferences: MPSettingsHelper ↔ NSUserDefaults.
c. Persistence Layer (Orange)
– Disk: KDB/KDBX files stored on filesystem.
– TemporaryFileStorage: cached decrypted files for editing.
– Sparkle Updater: checks GitHub for new releases.
d. External Services & Frameworks (Gray)
– Carthage frameworks (Sparkle, TransformerKit, MJGFoundation, DDHotKey).
– System services: NSUserNotificationCenter, keychain (if used), accessibility APIs for autotype.
– Plugins loaded at runtime from ~/Library/Application Support/MacPass/Plugins.

##### Data flow & control flow
- “Edit entry” loop: user → UI controller → MPDocument (model state change) → TemporaryFileStorage → eventually “Save” → model → KeePassKit → write KDBX.
- “Autotype” flow: user selects entry → UI → MPAutotypeParser → MPAutotypeDaemon → event injection (system).
- “Check for updates”: App launch → Sparkle framework → network → update dialog.
- “Load plugins”: App launch → MPPluginHost scans plugin bundles → loads code → registers menu items.

##### Architectural patterns & principles
- Cocoa MVC / Document-based application pattern.
- Single delegate per subsystem (AppDelegate, DocumentController, PluginHost).
- Loose coupling via helper classes (e.g., MPActionHelper, MPContextMenuHelper).
- Submodules to isolate third-party code & ease upgrades.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "UI Layer"
        direction TB
        XIB["XIBs (.xib files)"]:::ui
        EntryVC["MPEntryViewController"]:::ui
        ContextBarVC["MPContextBarViewController"]:::ui
        AutotypeBuilderVC["MPAutotypeBuilderViewController"]:::ui
    end

    subgraph "Application Layer"
        direction TB
        AppDelegate["MPAppDelegate"]:::app
        DocController["MPDocumentController"]:::app
        DocWinController["MPDocumentWindowController"]:::app
        DocSplitVC["MPDocumentSplitViewController"]:::app
    end

    subgraph "Core Logic Layer"
        direction TB
        DocModel["MPDocument"]:::core
        FormatExt["KPKFormat+MPUTIDetection"]:::core
        AutotypeParser["MPAutotypeParser"]:::core
        AutotypeCommand["MPAutotypeCommand"]:::core
        AutotypeDaemon["MPAutotypeDaemon"]:::core
        KeyTyper["MPKeyTyper"]:::core
        PluginHost["MPPluginHost"]:::core
        PluginContext["MPPluginEntryActionContext"]:::core
    end

    subgraph "Persistence Layer"
        direction TB
        Settings["MPSettingsHelper"]:::persistence
        TempStorage["MPTemporaryFileStorage"]:::persistence
        TempCenter["MPTemporaryFileStorageCenter"]:::persistence
        Attachments["MPDocument+Attachments"]:::persistence
        History["MPDocument+History"]:::persistence
    end

    subgraph "External Services & Frameworks"
        direction TB
        Carthage["Carthage Frameworks"]:::external
        DDHotKeyAdd["DDHotKey+MacPassAdditions"]:::external
        Sparkle["Sparkle Updater"]:::external
        SysAPIs["System APIs"]:::external
    end

    XIB -->|"openUI"| DocController
    DocController -->|"createDocument"| DocModel
    DocModel -->|"parseDatabase"| FormatExt
    FormatExt -->|"renderEntries"| EntryVC
    EntryVC -->|"selectEntry"| AutotypeParser
    AutotypeParser -->|"buildCommands"| AutotypeCommand
    AutotypeCommand -->|"startDaemon"| AutotypeDaemon
    AutotypeDaemon -->|"dispatchKeyEvents"| KeyTyper
    DocModel -->|"saveChanges"| TempStorage
    TempStorage -->|"serialize"| FormatExt
    FormatExt -->|"writeKDBX"| History
    AppDelegate -->|"launchApp"| Sparkle
    Sparkle -->|"checkUpdates"| SysAPIs
    AppDelegate -->|"loadPlugins"| PluginHost
    PluginHost -->|"registerContext"| PluginContext
    PluginHost -->|"loadBundles"| Carthage

    click XIB "https://github.com/macpass/macpass/blob/master/MacPass/Base.lproj/*.xib"
    click EntryVC "https://github.com/macpass/macpass/blob/master/MacPass/MPEntryViewController.h"
    click ContextBarVC "https://github.com/macpass/macpass/blob/master/MacPass/MPContextBarViewController.h"
    click AutotypeBuilderVC "https://github.com/macpass/macpass/blob/master/MacPass/MPAutotypeBuilderViewController.h"
    click AppDelegate "https://github.com/macpass/macpass/blob/master/MacPass/MPAppDelegate.h"
    click DocController "https://github.com/macpass/macpass/blob/master/MacPass/MPDocumentController.h"
    click DocWinController "https://github.com/macpass/macpass/blob/master/MacPass/MPDocumentWindowController.h"
    click DocSplitVC "https://github.com/macpass/macpass/blob/master/MacPass/MPDocumentSplitViewController.h"
    click DocModel "https://github.com/macpass/macpass/blob/master/MacPass/MPDocument.h"
    click FormatExt "https://github.com/macpass/macpass/blob/master/MacPass/KPKFormat+MPUTIDetection.h"
    click AutotypeParser "https://github.com/macpass/macpass/blob/master/MacPass/MPAutotypeParser.h"
    click AutotypeCommand "https://github.com/macpass/macpass/blob/master/MacPass/MPAutotypeCommand.h"
    click AutotypeDaemon "https://github.com/macpass/macpass/blob/master/MacPass/MPAutotypeDaemon.h"
    click KeyTyper "https://github.com/macpass/macpass/blob/master/MacPass/MPKeyTyper.h"
    click PluginHost "https://github.com/macpass/macpass/blob/master/MacPass/MPPluginHost.h"
    click PluginContext "https://github.com/macpass/macpass/blob/master/MacPass/MPPluginEntryActionContext.h"
    click Settings "https://github.com/macpass/macpass/blob/master/MacPass/MPSettingsHelper.h"
    click TempStorage "https://github.com/macpass/macpass/blob/master/MacPass/MPTemporaryFileStorage.h"
    click TempCenter "https://github.com/macpass/macpass/blob/master/MacPass/MPTemporaryFileStorageCenter.h"
    click Attachments "https://github.com/macpass/macpass/blob/master/MacPass/MPDocument+Attachments.m"
    click History "https://github.com/macpass/macpass/blob/master/MacPass/MPDocument+History.m"
    click Carthage "https://github.com/macpass/macpass/tree/master/Cartfile"
    click DDHotKeyAdd "https://github.com/macpass/macpass/blob/master/MacPass/DDHotKey+MacPassAdditions.h"
    click Sparkle "https://github.com/macpass/macpass/tree/master/Cartfile"

    classDef ui fill:#cce5ff,stroke:#0066cc
    classDef app fill:#d5f5e3,stroke:#2ecc71
    classDef core fill:#d4efdf,stroke:#27ae60
    classDef persistence fill:#f9e79f,stroke:#f1c40f
    classDef external fill:#d5dbdb,stroke:#7f8c8d
```
