How macpass/macpass works
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.