# theprimeagen/harpoon architecture

> Architecture diagram of the GitHub repository theprimeagen/harpoon, 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/theprimeagen/harpoon
- Repository: https://github.com/theprimeagen/harpoon

## Overview

##### Main Components
- Core Library – This is the heart of the plugin that handles configuration (via the setup function), global settings, and the common utilities (lua/harpoon/utils.lua).
- Management – Contained in lua/harpoon/mark.lua, this manages marks (i.e., saving file positions and related metadata) and acts as the interface to add or retrieve file marks.
- User Interface (UI) – Found in lua/harpoon/ui.lua, this module handles the display of a quick menu that allows users to navigate through marked files.
- Terminal Management – lua/harpoon/term.lua handles the creation, navigation (gotoTerminal), and sending commands to persistent terminal sessions.
- Command UI – Lua/harpoon/cmd-ui.lua provides an interface for preconfiguring and sending commands to terminals.
- Tmux Integration – lua/harpoon/tmux.lua ensures that terminal operations can work seamlessly with tmux (e.g., switching windows, sending commands, etc.), supported further by dedicated scripts (scripts/tmux/…).
- Telescope Extension – Under lua/telescope/_extensions (harpoon.lua and marks.lua), these modules register Harpoon with Telescope so that users can navigate marks via Telescope’s fuzzy finder.
- Tests – The tests under lua/harpoon/test help validate core functionalities and interactions between the components.

##### Relationships and Interactions
- The Core Library interacts with all modules: it initializes the plugin with setup({…}) and provides global configuration.
- The Mark Management module is invoked by both the UI (for displaying available marks) and by developers using commands (e.g., to add a file).
- The UI module gathers the list of marks from the Mark Management module and lets users select a file to navigate to.
- Terminal Management and Tmux Integration form a pair. When a user sends a command (via the Command UI or directly) or navigates to a terminal, Terminal Management will either create or switch context; if tmux support is enabled, it routes the command via Tmux Integration.
- The Telescope Extension interfaces with core Harpoon functionalities (especially Marks) to integrate with the fuzzy finder provided by Telescope.

##### Architectural Patterns and Principles
- Modular Design: Each major functionality (marks, ui, terminal, tmux, telescope extension) is implemented as a separate Lua module.
- Separation of Concerns: UI, state management, and terminal/tmux logic are clearly separated to allow easier maintenance and possible future extensions.
- Extensibility: The plugin is designed in a way that additional features (like new Telescope extensions) can be easily added.
- Testability: The inclusion of test files in lua/harpoon/test indicates an emphasis on verifying each component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    NV["Neovim (User)"]:::external
    HCore["Harpoon Core"]:::core

    subgraph "Navigation/Marking"
        UIM["UI Module"]:::nav
        MarkM["Mark Management"]:::nav
        TelExt["Telescope Extension"]:::nav
        TelMarks["Telescope Marks"]:::nav
    end

    subgraph "Terminal Interaction"
        CMDUI["Command UI"]:::term
        TermM["Terminal Management"]:::term
        Tmux["Tmux Integration"]:::term
        TmuxScript["Tmux Script"]:::term
    end

    TestS["Test Suite"]:::test

    %% Relationships
    NV -->|"triggers"| HCore
    HCore -->|"initializes"| UIM
    HCore -->|"initializes"| MarkM
    HCore -->|"initializes"| CMDUI
    HCore -->|"initializes"| TermM
    HCore -->|"configures"| TelExt

    UIM -->|"retrieves"| MarkM
    TelExt -->|"queries"| MarkM

    CMDUI -->|"sends commands"| TermM
    TermM -->|"integrates with"| Tmux
    Tmux -->|"utilizes"| TmuxScript

    TestS -->|"validates"| HCore

    %% Click Events
    click HCore "https://github.com/theprimeagen/harpoon/blob/master/lua/harpoon/init.lua"
    click MarkM "https://github.com/theprimeagen/harpoon/blob/master/lua/harpoon/mark.lua"
    click UIM "https://github.com/theprimeagen/harpoon/blob/master/lua/harpoon/ui.lua"
    click TermM "https://github.com/theprimeagen/harpoon/blob/master/lua/harpoon/term.lua"
    click CMDUI "https://github.com/theprimeagen/harpoon/blob/master/lua/harpoon/cmd-ui.lua"
    click Tmux "https://github.com/theprimeagen/harpoon/blob/master/lua/harpoon/tmux.lua"
    click TmuxScript "https://github.com/theprimeagen/harpoon/tree/master/scripts/tmux/switch-back-to-nvim"
    click TelExt "https://github.com/theprimeagen/harpoon/blob/master/lua/telescope/_extensions/harpoon.lua"
    click TelMarks "https://github.com/theprimeagen/harpoon/blob/master/lua/telescope/_extensions/marks.lua"
    click TestS "https://github.com/theprimeagen/harpoon/tree/master/lua/harpoon/test"

    %% Styles
    classDef core fill:#FFA500,stroke:#000,stroke-width:2px
    classDef nav fill:#87CEFA,stroke:#000,stroke-width:2px
    classDef term fill:#90EE90,stroke:#000,stroke-width:2px
    classDef test fill:#D3D3D3,stroke:#000,stroke-width:2px
    classDef external fill:#FFFFFF,stroke:#000,stroke-width:2px
```
