# p0deje/maccy architecture

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

- Interactive diagram: https://gitdiagram.com/p0deje/maccy
- Repository: https://github.com/p0deje/maccy

## Overview

##### Project Type and Purpose
- Maccy is a lightweight clipboard manager for macOS. It is designed as a native application written in Swift, with an emphasis on speed, minimalism, and a keyboard-first interface.
- The README clearly describes its usage (copy/paste history, searching, keyboard shortcuts) while the file tree shows that it’s an Xcode project with multiple source files, assets, localized strings, models (using Core Data), and design resources.

##### File Structure
- The top-level directories indicate design assets (under “Designs”), the Xcode project files (“Maccy.xcodeproj”), and the main application code in the “Maccy” directory.
- Inside “Maccy” you see:
- App entry points (e.g., MaccyApp.swift, AppDelegate.swift) for initializing the application.
- Various Swift files implementing features like clipboard handling, history management, search, notifications, and settings UI.
- Directories like Models, Views, Observables, and Extensions – suggesting an architecture that might follow patterns such as MVVM (model–view–viewmodel) or a modular MVC.
- Core data models for history (e.g., History.xcdatamodeld and Storage.xcdatamodeld) that show persistence layers.
- There are localized strings and design assets which imply strong support for internationalization and custom UI layout/design.
- Test directories (MaccyTests and MaccyUITests) indicate a structured testing strategy.

##### Components to Highlight
a. Main Application Component:
- Maccy App entry where the application is bootstrapped (MaccyApp.swift & AppDelegate.swift).
b. User Interface (UI) Layer:
- Views folder: multiple SwiftUI or Cocoa-based views (e.g., ContentView, PreviewItemView, HistoryListView) that build the native macOS UI.
- Settings components (AdvancedSettingsPane, AppearanceSettingsPane, etc.) that allow user customization.
c. Clipboard & Input Handling:
- GlobalHotKey, KeyboardShortcuts, and Clipboard.swift. This layer monitors the clipboard, handles shortcut triggers, and interacts with system accessibility.
d. Data and Persistence Layer:
- Models (HistoryItem, HistoryItemContent) and Core Data models (History.xcdatamodeld, Storage.xcdatamodeld) managing the clipboard history and storage.
e. Observables and State Management:
- Observables directory (AppState, History, Popup, etc.) which facilitate reactive data flow and UI updates.
f. Supporting Services:
- Notifier.swift for system notifications.
- Sorting and Storage services (Sorter.swift, Storage.swift) which handle organization and persistence of clipboard items.

##### Relationships and Interactions
- The application listens to clipboard changes via the Clipboard module.
- Clipboard events are captured by a dedicated service (GlobalHotKey and associated keyboard shortcut management) and then passed on to a data manager that creates or updates HistoryItems.
- Data flows into Models and is persisted using the Core Data model. The Observables update the UI in real time.
- User actions on views (picking an item, searching, deleting) trigger interactions that notify the Models, update the persisted state, and reflect back into the UI.
- Settings and Preferences (handled in a separate section) provide customization for features like ignoring certain clipboard types or adjusting clipboard check intervals.

##### Architectural Patterns and Design Principles
- The separation of concerns is clear: UI components, business logic (clipboard processing, history management), and persistence (Core Data).
- There appears to be an adoption of reactive or observable patterns (with the “Observables” directory) that help bridge data changes from the backend to the front-end.
- The codebase is modular—extensions, localized resources, and testing modules further segment functionality.
- The use of MVC or MVVM patterns can be inferred: Models (clipboard history), Observables (state/view models), and Views provide a clean separation between data, logic, and presentation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Entry
    subgraph "Application Entry"
        A1["MaccyApp.swift"]:::appComp
        A2["AppDelegate.swift"]:::appComp
    end

    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1["ContentView"]:::ui
        UI2["HistoryListView"]:::ui
        UI3["PreviewItemView"]:::ui
        UI_Settings["Settings UI (Advanced/Apearance/General/Ignore)"]:::ui
    end

    %% Clipboard & Input Handling
    subgraph "Clipboard & Input Handling"
        CI1["Clipboard.swift"]:::logic
        CI2["GlobalHotKey.swift"]:::logic
        CI3["KeyboardShortcuts Extension"]:::logic
        CI4["KeyChord.swift"]:::logic
        CI5["KeyShortcut.swift"]:::logic
    end

    %% Data & Persistence Layer
    subgraph "Data & Persistence Layer"
        DP1["HistoryItem.swift"]:::persistence
        DP2["HistoryItemContent.swift"]:::persistence
        DP3["Core Data (History)"]:::persistence
        DP4["Core Data (Storage)"]:::persistence
        DP5["Storage.swift"]:::persistence
    end

    %% Observables / State Management
    subgraph "Observables / State Management"
        O1["AppState"]:::observable
        O2["History Observable"]:::observable
        O3["Popup"]:::observable
    end

    %% Supporting Services
    subgraph "Supporting Services"
        S1["Notifier.swift"]:::service
        S2["Sorter.swift"]:::service
        S3["Extensions Utilities"]:::service
    end

    %% Data Flow and Interactions
    CI1 -->|"updates"| DP1
    CI1 -->|"triggers"| CI2
    CI2 -->|"activates"| CI3
    CI2 -->|"activates"| CI4
    CI2 -->|"activates"| CI5

    DP1 -->|"persists to"| DP3
    DP1 -->|"persists to"| DP4
    DP5 -->|"handles"| DP3

    DP1 -->|"notifies"| O1
    DP2 -->|"notifies"| O2

    O1 -->|"updates"| UI1
    O2 -->|"updates"| UI2
    O3 -->|"controls"| UI3

    UI1 -->|"triggers"| O1
    UI2 -->|"triggers"| O2
    UI_Settings -->|"modifies"| S1

    CI1 -->|"sends events"| O3
    S1 -->|"notifies"| UI1

    %% Application Bootstrapping
    A1 -->|"initializes"| UI1
    A1 -->|"initializes"| CI1
    A1 -->|"initializes"| O1

    %% Supporting Services Integration
    S2 -->|"organizes"| DP5
    S3 -->|"utilities for"| CI3
    S3 -->|"utilities for"| DP5

    %% Click Events
    click A1 "https://github.com/p0deje/maccy/blob/master/Maccy/MaccyApp.swift"
    click A2 "https://github.com/p0deje/maccy/blob/master/Maccy/AppDelegate.swift"
    click UI1 "https://github.com/p0deje/maccy/blob/master/Maccy/Views/ContentView.swift"
    click UI2 "https://github.com/p0deje/maccy/blob/master/Maccy/Views/HistoryListView.swift"
    click UI_Settings "https://github.com/p0deje/maccy/tree/master/Maccy/Settings"
    click CI1 "https://github.com/p0deje/maccy/blob/master/Maccy/Clipboard.swift"
    click CI2 "https://github.com/p0deje/maccy/blob/master/Maccy/GlobalHotKey.swift"
    click CI3 "https://github.com/p0deje/maccy/blob/master/Maccy/Extensions/KeyboardShortcuts.Name+Shortcuts.swift"
    click CI4 "https://github.com/p0deje/maccy/blob/master/Maccy/KeyChord.swift"
    click CI5 "https://github.com/p0deje/maccy/blob/master/Maccy/KeyShortcut.swift"
    click DP1 "https://github.com/p0deje/maccy/blob/master/Maccy/Models/HistoryItem.swift"
    click DP2 "https://github.com/p0deje/maccy/blob/master/Maccy/Models/HistoryItemContent.swift"
    click DP3 "https://github.com/p0deje/maccy/blob/master/Maccy/History.xcdatamodeld"
    click DP4 "https://github.com/p0deje/maccy/blob/master/Maccy/Storage.xcdatamodeld"
    click DP5 "https://github.com/p0deje/maccy/blob/master/Maccy/Storage.swift"
    click O1 "https://github.com/p0deje/maccy/blob/master/Maccy/Observables/AppState.swift"
    click O2 "https://github.com/p0deje/maccy/blob/master/Maccy/Observables/History.swift"
    click O3 "https://github.com/p0deje/maccy/blob/master/Maccy/Observables/Popup.swift"
    click S1 "https://github.com/p0deje/maccy/blob/master/Maccy/Notifier.swift"
    click S2 "https://github.com/p0deje/maccy/blob/master/Maccy/Sorter.swift"
    click S3 "https://github.com/p0deje/maccy/tree/master/Maccy/Extensions"

    %% Styles
    classDef appComp fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
    classDef ui fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef logic fill:#bbdefb,stroke:#1565c0,stroke-width:2px;
    classDef persistence fill:#ffcdd2,stroke:#c62828,stroke-width:2px;
    classDef observable fill:#d1c4e9,stroke:#4527a0,stroke-width:2px;
    classDef service fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
```
