# nattie-nkosi/pdf-merger architecture

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

- Interactive diagram: https://gitdiagram.com/nattie-nkosi/pdf-merger
- Repository: https://github.com/nattie-nkosi/pdf-merger

## Overview

##### Main Components
- GUI Frontend (Electron Renderer Process):
- index.html, styles.css, renderer.js – these files support the interface.
- preload.js – serves as a secure bridge between the renderer and main process.
- Electron Main Process:
- main.js – initializes and manages the Electron application lifecycle.
- CLI Interface:
- cli.js – implements command-line functionality for automation.
- Core PDF Merging Library:
- index.js – potentially coordinates the PDF merge operations (and may act as a common entry point for both the GUI and CLI modes).
- Build/Configuration and Assets:
- package.json and package-lock.json – show dependencies, scripts, and configuration.
- check-files.js and dist/builder-effective-config.yaml – might be related to build checks or packaging steps.
- assets/screenshots – store UI-related assets for documentation or usage in the GUI.

##### Relationships and Interactions
- In GUI mode:
- The main process (main.js) launches the Electron window and loads index.html.
- The preload.js file securely exposes specific APIs to the renderer process (renderer.js) which manages the interactive UI.
- User interactions on the interface (via renderer.js) trigger PDF merge operations that might call shared functions in index.js or a dedicated merge module.
- In CLI mode:
- The cli.js file is the entry point when running in CLI-only mode. It parses command-line parameters (like input directory, output file, and merge options) and invokes the PDF merging functions.
- Both modes likely rely on a central PDF merge functionality (which may be imported from index.js or another module) that implements sorting, filtering (with regex patterns), and bookmarks addition.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Distinct responsibilities between the GUI (Electron renderer process) and CLI modes, with shared logic for PDF merging.
- Modular Architecture: Independent modules for user interface, command-line logic, and core business logic (PDF merging).
- Dependency Injection/Callbacks: For instance, the programmatic usage example shows passing callbacks (like onProgress) to the merge function.
- Cross-Platform Design: The use of Electron ensures that the GUI works on Windows, macOS, and Linux, while the CLI remains lightweight.

##### Including Technologies and Frameworks
- Electron: Handles cross-platform GUI.
- Node.js: Underpins both CLI and Electron’s main process.
- NPM Packages: Used for merging PDFs and managing dependencies.
- Other tools like check-files.js hint at pre-check scripts or build processes, and dist/builder-effective-config.yaml suggests configuration for packaging or deployment.

##### Specific Elements
- Electron Main Process: Include main.js and link to preload.js.
- Electron Renderer Process: Include index.html, renderer.js, and styles.css.
- CLI Component: Show the cli.js file and note its alternative mode.
- How the Main Process invokes the Renderer via Electron.
- Communication between Renderer and Main processes through preload.js.
- CLI calls merging functions directly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GUI Mode Subgraph
    subgraph "GUI Mode"
        direction TB
        A["Electron Main Process (main.js)"]:::gui
        B["Secure Bridge (preload.js)"]:::gui
        A -->|"launches"| B
        subgraph "Renderer Process"
            direction TB
            C["index.html"]:::gui
            D["renderer.js"]:::gui
            E["styles.css"]:::gui
        end
        B --> C
        B --> D
        B --> E
        C -->|"triggersMerge"| G["Shared Core PDF Merge (index.js)"]:::core
        D -->|"callsMerge"| G
    end

    %% CLI Mode Subgraph
    subgraph "CLI Mode"
        direction TB
        F["CLI Interface (cli.js)"]:::cli
        F -->|"invokesMerge"| G
    end

    %% Build & Configuration and Assets Subgraph
    subgraph "Build & Configuration & Assets"
        direction TB
        H["NPM Config (package.json)"]:::build
        I["NPM Lock (package-lock.json)"]:::build
        J["Build Check (check-files.js)"]:::build
        K["Builder Config (dist/builder-effective-config.yaml)"]:::build
        L["UI Assets (assets/screenshots)"]:::build
    end

    %% Supporting Relationships from Build & Config to Runtime Components
    H --- A
    I --- A
    J --- A
    K --- A
    L --- C

    %% Class Definitions for Color Coding
    classDef gui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef cli fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef core fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef build fill:#f8d7da,stroke:#721c24,stroke-width:2px;

    %% Click Events
    click C "https://github.com/nattie-nkosi/pdf-merger/blob/main/index.html"
    click D "https://github.com/nattie-nkosi/pdf-merger/blob/main/renderer.js"
    click E "https://github.com/nattie-nkosi/pdf-merger/blob/main/styles.css"
    click B "https://github.com/nattie-nkosi/pdf-merger/blob/main/preload.js"
    click A "https://github.com/nattie-nkosi/pdf-merger/blob/main/main.js"
    click F "https://github.com/nattie-nkosi/pdf-merger/blob/main/cli.js"
    click G "https://github.com/nattie-nkosi/pdf-merger/blob/main/index.js"
    click H "https://github.com/nattie-nkosi/pdf-merger/blob/main/package.json"
    click I "https://github.com/nattie-nkosi/pdf-merger/blob/main/package-lock.json"
    click J "https://github.com/nattie-nkosi/pdf-merger/blob/main/check-files.js"
    click K "https://github.com/nattie-nkosi/pdf-merger/blob/main/dist/builder-effective-config.yaml"
    click L "https://github.com/nattie-nkosi/pdf-merger/tree/main/assets/screenshots"
```
