# doganarif/llmdog architecture

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

- Interactive diagram: https://gitdiagram.com/doganarif/llmdog
- Repository: https://github.com/doganarif/llmdog

## Overview

##### Project Type and Purpose
- LLMDog is a single‐binary, full‐featured command‑line (CLI) application written in Go.
- Purpose: Let developers interactively select files from a codebase (respecting .gitignore), format them as Markdown (with a tree view and syntax highlighting), and copy the result to the clipboard for seamless pasting into any LLM chat.

##### High‑Level Architectural Overview
- Layered structure following a clean/hexagonal style:
- Entry‑Point / Orchestration
- Presentation (TUI)
- Business Logic (file selection, git filtering, markdown formatting)
- Domain Model (tree nodes, file metadata)
- Infrastructure / External Interfaces (OS filesystem, git, clipboard, terminal)

##### Key Components
a. Entry‑Point
- cmd/llmdog/main.go
- Reads command‑line flags, loads .gitignore, initializes subsystems (UI, business logic).
b. Presentation Layer (internal/ui)
- internal/ui/ui.go: generic TUI framework wiring
- internal/ui/bookmark_ui.go: the interactive file/directory selector with key bindings, live preview pane
- Depends on Bubble Tea & Lip Gloss for rendering
c. Business Logic
- internal/bookmarks/bookmarks.go: recursive traversal & selection logic, respects gitignore rules
- internal/git/git.go: reads and parses .gitignore, provides include/exclude filters
- Markdown generation (likely part of bookmarks or ui packages): builds a Markdown string with tree and code blocks
d. Domain Model
- internal/model/model.go: definitions for FileNode, DirectoryNode, metadata (path, contents)
- Used by both the bookmarks and UI layers for a consistent in‑memory representation
e. Infrastructure / External Interfaces
- File System: os.Open, filepath.Walk
- Gitignore: parsing .gitignore lines, patterns
- Clipboard: shelling out (`pbcopy`, `xclip`, Windows equivalent) or Go‑clipboard library

##### Relationships & Data Flow
1. User invokes `llmdog` in their shell
2. main.go
→ initializes `git` filter, loads ignore patterns
→ scans directory via `bookmarks` package to build a tree of `model.FileNode`/`DirectoryNode`
→ passes the tree to the UI layer
3. UI layer
← presents tree, handles navigation and selections
→ on “Enter”, emits a list of selected nodes back to orchestration
4. Business logic
→ formats selected nodes into a Markdown document (with file tree, syntax‐highlighted code blocks)
5. Infrastructure
→ pipes Markdown text to the OS clipboard
→ prints a success message to the terminal
6. User pastes into an LLM chat

##### Architectural Patterns & Principles
- Separation of Concerns: each internal package has a single responsibility (UI vs. git filtering vs. model).
- Dependency Rule: outer layers (UI, Orchestration) depend on inner layers (Business Logic, Model), but not vice versa.
- Hexagonal / Ports & Adapters: the “business” core has no direct calls to OS—those are abstracted behind small adapter layers in `internal/git` and clipboard calls in `internal/ui`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external
    subgraph "Entry-Point / Orchestrator"
        Orchestrator["cmd/llmdog/main.go\n(Go 1.16+ runtime)"]:::orchestrator
    end

    subgraph "Presentation Layer"
        UIFW["Generic TUI Framework"]:::ui
        BookmarkUI["Interactive File/Directory Selector"]:::ui
    end

    subgraph "Business Logic"
        Bookmarks["File Traversal & Selection Engine"]:::biz
        GitFilter[".gitignore Parser & Filter Adapter"]:::biz
        MarkdownGen["Markdown Generator"]:::biz
    end

    subgraph "Domain Model"
        Model["FileNode/DirectoryNode Definitions"]:::model
    end

    subgraph "External Interfaces"
        FS[(File System)]:::ext
        GitignoreFile[(.gitignore Patterns)]:::ext
        Clipboard[(OS Clipboard)]:::ext
        Terminal[(Terminal I/O)]:::ext
    end

    User -->|invokes CLI| Orchestrator
    Orchestrator -->|loads patterns| GitFilter
    Orchestrator -->|scans directory| Bookmarks
    Bookmarks -->|uses Model| Model
    Bookmarks -->|applies filters| GitFilter
    Orchestrator -->|passes tree| BookmarkUI
    BookmarkUI -->|renders| UIFW
    BookmarkUI -->|on Enter emit selected nodes| MarkdownGen
    MarkdownGen -->|uses Model| Model
    MarkdownGen -->|writes doc| Clipboard
    Clipboard -->|prints success| Terminal

    classDef orchestrator fill:#f9f,stroke:#333,stroke-width:2px
    classDef ui fill:#bfb,stroke:#333,stroke-width:2px
    classDef biz fill:#bbf,stroke:#333,stroke-width:2px
    classDef model fill:#eee,stroke:#333,stroke-width:2px
    classDef ext fill:#fbb,stroke:#333,stroke-width:2px
    classDef external fill:#ccc,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5

    class User external

    click Orchestrator "https://github.com/doganarif/llmdog/blob/main/cmd/llmdog/main.go"
    click UIFW "https://github.com/doganarif/llmdog/blob/main/internal/ui/ui.go"
    click BookmarkUI "https://github.com/doganarif/llmdog/blob/main/internal/ui/bookmark_ui.go"
    click Bookmarks "https://github.com/doganarif/llmdog/blob/main/internal/bookmarks/bookmarks.go"
    click GitFilter "https://github.com/doganarif/llmdog/blob/main/internal/git/git.go"
    click Model "https://github.com/doganarif/llmdog/blob/main/internal/model/model.go"
```
