# jamf/replicator architecture

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

- Interactive diagram: https://gitdiagram.com/jamf/replicator
- Repository: https://github.com/jamf/replicator

## Overview

##### Project Type & Purpose
- The project is a macOS desktop application (built in Xcode using Swift) designed to synchronize configurations between Jamf Pro servers. Its purpose is to export configurations (as XML) from one server and import (or delete) items on another. It also handles additional tasks such as removing configurations and running in a headless/command-line mode.
- The README and file structure make it clear that the app serves as both a UI-based tool and a command-line utility for server replication and configuration management.

##### Key Components from the File Tree
- Xcode Project Structure: The presence of Replicator.xcodeproj and its workspace files indicate a typical Xcode project structure.
- Application Source Code: The “Replicator” folder contains the bulk of the Swift files. These files are divided by functionality:
- UI Elements & App Lifecycle: Files like AppDelegate.swift, Main.storyboard, Preferences.storyboard, HelpViewController.swift, SummaryViewController.swift, and various view controller files that manage the user interface.
- Business/Controller Logic: Files such as CreateEndpoints.swift, Cleanup.swift, Headless.swift, ExistingObjects.swift, RemoveData.swift, and RemoveObjects.swift represent the logic to handle operations (export, replication, deletion, etc.).
- API Integration & Communication: Files like JamfPro.swift, Jpapi.swift, EndpointXml.swift, and Credentials.swift handle interactions with the Jamf Pro API.
- Data Handling & Utility Functions: Classes such as Json.swift, JsonObjects.swift, LoggerExtension.swift, Utilities.swift, WriteToLog.swift, and SecurityScopedBookmarks.swift deal with data transformation, logging, and handling special macOS security features.
- Preferences & Settings: Dedicated files like PreferencesViewController.swift, PrefsWindowController.swift, and settings.plist take care of user or app configuration.
- Additional Assets: The images folder, Assets.xcassets, and index.html indicate UI assets and documentation resources.

##### Analysis of the README
- The README expands on the app’s features, outlining its usage in replicating, exporting/importing configurations, managing API authentication, and handling command-line operations.
- It explains various replication limitations and operational modes (e.g., removal mode via a file flag) and includes instructions for running commands.
- The README also details important dependency and ordering considerations (for example, how sites must be replicated before policies that reference them).

a. Main Components to Represent:
- User Interface Layer:
- UI components (storyboards, view controllers like PreferencesViewController, HelpViewController, SummaryViewController, etc.).
- Window management and interactive dialogs (alerts, file selection for export/import, summary displays).
- Application Logic/Controller Layer:
- Modules for handling replication logic (e.g., CreateEndpoints.swift, Cleanup.swift, and Headless.swift for command-line mode).
- Flow control for exporting, updating, and deleting configurations based on user input.
- API Integration & Communication Layer:
- API interfaces (JamfPro.swift, Jpapi.swift) that handle communication with Jamf Pro servers.
- Credential management (Credentials.swift) for authentication with source/destination servers.
- Modules for transforming data (Json.swift, JsonObjects.swift, EndpointXml.swift).
- Data Handling and Persistence:
- XML export/import management (files like ExportItem.swift, SaveDelegate.swift).
- Local file management for logs (logging utilities and configuration files like settings.plist).
- Command-Line Interface:
- A distinct pathway invoked when the app is run with command-line arguments (handled by Headless.swift and related functions).
- Utility and Support Modules:
- Logging (LoggerExtension.swift, WriteToLog.swift).
- Utility functions and common global configurations (Globals.swift, Utilities.swift).
- Security, such as handling security scoped bookmarks for file access.

b. Relationships and Interactions:
- User actions in the UI trigger events that flow into the Application Logic.
- The Application Logic calls the API Integration layer to fetch or push data.
- Data handling modules process the XML and JSON objects that represent Jamf Pro configurations.
- A command-line interface should be depicted as a parallel entry point that interacts with the same core components (logic layer and API integration).
- Log generation and error handling flow back into the UI (e.g., summary and status views) and log files.

c. Architectural Patterns & Principles:
- MVC/MVVM: Even if not strictly enforced, the separation between view controllers (UI), data handling (models), and business logic (controllers) is noticeable.
- Layered Architecture: Clear separation between presentation (UI), business logic (core replication logic), and data/integration (API calls, file I/O).
- Modular design: Individual Swift files handle discrete operations (preferences, export, deletion) facilitating clear boundaries.

d. Notable Technologies/Frameworks:
- Swift and Xcode for a macOS application.
- Cocoa frameworks (AppKit) for UI components.
- URLSession or similar API handling for HTTP communication with Jamf Pro servers.
- XML and JSON processing libraries integrated within Swift.
- macOS-specific features (security scoped bookmarks, keychain access).

##### Instructing the Principal Software Engineer
- Detail interactions: for instance, demonstrate how selecting an export operation via the UI causes the Replication Engine to call the JamfPro API through the API module, while logging is handled simultaneously by the Log Manager.
- Branching between interactive (GUI) and non-interactive (CLI) modes but show their shared core modules.
- Capturing the dependency ordering noted in the README (e.g., the need to replicate certain items before others) which is enforced by the replication logic in the application.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI1["Main.storyboard"]
        UI2["Preferences.storyboard"]
        UI3["HelpViewController.swift"]
        UI4["SummaryViewController.swift"]
        UI5["PreferencesViewController.swift"]
        UI6["PrefsWindowController.swift"]
        UI7["ViewController.swift"]
    end

    %% Application Logic/Controller Layer
    subgraph "Application Logic Layer"
        L1["CreateEndpoints.swift"]
        L2["Cleanup.swift"]
        L3["ExistingObjects.swift"]
        L4["RemoveData.swift"]
        L5["RemoveObjects.swift"]
        L6["Headless.swift"]
    end

    %% API Integration & Communication Layer
    subgraph "API Integration & Communication Layer"
        A1["JamfPro.swift"]
        A2["Jpapi.swift"]
        A3["Credentials.swift"]
        A4["EndpointXml.swift"]
    end

    %% Data Handling & Persistence
    subgraph "Data Handling & Persistence"
        D1["ExportItem.swift"]
        D2["SaveDelegate.swift"]
        D3["XmlDelegate.swift"]
        D4["Json.swift"]
        D5["JsonObjects.swift"]
        D6["WriteToLog.swift"]
        D7["LoggerExtension.swift"]
    end

    %% Utility and Support Modules
    subgraph "Utility and Support Modules"
        U1["Globals.swift"]
        U2["Utilities.swift"]
        U3["SecurityScopedBookmarks.swift"]
        U4["Alert.swift"]
        U5["IconDelegate.swift"]
        U6["ObjectDelegate.swift"]
        U7["PackagesDelegate.swift"]
        U8["PatchDelegate.swift"]
        U9["TimeDelegate.swift"]
    end

    %% Additional Assets & Resources
    subgraph "Additional Assets & Resources"
        AR1["Assets.xcassets"]
        AR2["images"]
        AR3["index.html"]
        AR4["README.md"]
        AR5["settings.plist"]
    end

    %% Connections between layers
    UI7 -->|"triggers"| L1
    UI3 -->|"triggers"| L2
    UI4 -->|"displays"| L3
    L6 -->|"invokes"| L1

    %% Application Logic interacts with API Integration
    L1 -->|"calls"| A1
    L1 -->|"calls"| A2
    L2 -->|"calls"| A3
    L2 -->|"calls"| A4
    A1 -->|"returns"| L1
    A2 -->|"returns"| L1

    %% Application Logic interacts with Data Handling & Persistence
    L2 -->|"processes"| D1
    L3 -->|"processes"| D2
    L4 -->|"processes"| D3
    L5 -->|"processes"| D4

    %% Data Handling utilizes Logging
    D1 -->|"logs"| D6
    D2 -->|"logs"| D7
    D6 -->|"utilizes"| U4
    D7 -->|"utilizes"| U4

    %% Application Logic makes use of Utility/Support modules
    L1 -->|"uses"| U2
    U2 -->|"supports"| L2

    %% Parallel Command-Line Interface (CLI) aspect
    UI7 ---|"parallel_with"| L6

    %% Additional Assets providing resources and documentation
    AR1 ---|"resources"| UI7
    AR2 ---|"resources"| UI7
    AR3 ---|"documentation"| UI3
    AR4 ---|"documentation"| UI3
    AR5 ---|"configuration"| UI5

    %% Click Events for User Interface Layer
    click UI1 "https://github.com/jamf/replicator/blob/main/Replicator/Base.lproj/Main.storyboard"
    click UI2 "https://github.com/jamf/replicator/blob/main/Replicator/Base.lproj/Preferences.storyboard"
    click UI3 "https://github.com/jamf/replicator/blob/main/Replicator/HelpViewController.swift"
    click UI4 "https://github.com/jamf/replicator/blob/main/Replicator/SummaryViewController.swift"
    click UI5 "https://github.com/jamf/replicator/blob/main/Replicator/Preferences/PreferencesViewController.swift"
    click UI6 "https://github.com/jamf/replicator/blob/main/Replicator/PrefsWindowController.swift"
    click UI7 "https://github.com/jamf/replicator/blob/main/Replicator/ViewController.swift"

    %% Click Events for Application Logic/Controller Layer
    click L1 "https://github.com/jamf/replicator/blob/main/Replicator/CreateEndpoints.swift"
    click L2 "https://github.com/jamf/replicator/blob/main/Replicator/Cleanup.swift"
    click L3 "https://github.com/jamf/replicator/blob/main/Replicator/ExistingObjects.swift"
    click L4 "https://github.com/jamf/replicator/blob/main/Replicator/RemoveData.swift"
    click L5 "https://github.com/jamf/replicator/blob/main/Replicator/RemoveObjects.swift"
    click L6 "https://github.com/jamf/replicator/blob/main/Replicator/Headless.swift"

    %% Click Events for API Integration & Communication Layer
    click A1 "https://github.com/jamf/replicator/blob/main/Replicator/JamfPro.swift"
    click A2 "https://github.com/jamf/replicator/blob/main/Replicator/Jpapi.swift"
    click A3 "https://github.com/jamf/replicator/blob/main/Replicator/Credentials.swift"
    click A4 "https://github.com/jamf/replicator/blob/main/Replicator/EndpointXml.swift"

    %% Click Events for Data Handling & Persistence
    click D1 "https://github.com/jamf/replicator/blob/main/Replicator/ExportItem.swift"
    click D2 "https://github.com/jamf/replicator/blob/main/Replicator/SaveDelegate.swift"
    click D3 "https://github.com/jamf/replicator/blob/main/Replicator/XmlDelegate.swift"
    click D4 "https://github.com/jamf/replicator/blob/main/Replicator/Json.swift"
    click D5 "https://github.com/jamf/replicator/blob/main/Replicator/JsonObjects.swift"
    click D6 "https://github.com/jamf/replicator/blob/main/Replicator/WriteToLog.swift"
    click D7 "https://github.com/jamf/replicator/blob/main/Replicator/LoggerExtension.swift"

    %% Click Events for Utility and Support Modules
    click U1 "https://github.com/jamf/replicator/blob/main/Replicator/Globals.swift"
    click U2 "https://github.com/jamf/replicator/blob/main/Replicator/Utilities.swift"
    click U3 "https://github.com/jamf/replicator/blob/main/Replicator/SecurityScopedBookmarks.swift"
    click U4 "https://github.com/jamf/replicator/blob/main/Replicator/Alert.swift"
    click U5 "https://github.com/jamf/replicator/blob/main/Replicator/IconDelegate.swift"
    click U6 "https://github.com/jamf/replicator/blob/main/Replicator/ObjectDelegate.swift"
    click U7 "https://github.com/jamf/replicator/blob/main/Replicator/PackagesDelegate.swift"
    click U8 "https://github.com/jamf/replicator/blob/main/Replicator/PatchDelegate.swift"
    click U9 "https://github.com/jamf/replicator/blob/main/Replicator/TimeDelegate.swift"

    %% Click Events for Additional Assets & Resources
    click AR1 "https://github.com/jamf/replicator/blob/main/Replicator/Assets.xcassets"
    click AR2 "https://github.com/jamf/replicator/tree/main/Replicator/images"
    click AR3 "https://github.com/jamf/replicator/blob/main/Replicator/index.html"
    click AR4 "https://github.com/jamf/replicator/blob/main/README.md"
    click AR5 "https://github.com/jamf/replicator/blob/main/settings.plist"

    %% Styles: Color Definitions
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef logic fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef api fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef data fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef util fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef asset fill:#D3D3D3,stroke:#000,stroke-width:1px;

    class UI1,UI2,UI3,UI4,UI5,UI6,UI7 ui;
    class L1,L2,L3,L4,L5,L6 logic;
    class A1,A2,A3,A4 api;
    class D1,D2,D3,D4,D5,D6,D7 data;
    class U1,U2,U3,U4,U5,U6,U7,U8,U9 util;
    class AR1,AR2,AR3,AR4,AR5 asset;
```
