# skardyy/ttyimg architecture

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

- Interactive diagram: https://gitdiagram.com/skardyy/ttyimg
- Repository: https://github.com/skardyy/ttyimg

## Overview

##### Main Components
- Command Line Interface (CLI) — represented by main.go. This is the entry point where user parameters (image path, resizing options, protocol selection etc.) are processed.
- Image Processing Module — represented by images_manipulation.go and images_query.go. This module handles loading images, scaling, and applying encoding logic.
- OS or Platform Abstraction Layer — represented by platform-specific files (attrs.go, attrs_unix.go, attrs_windows.go). This layer abstracts terminal size querying (cells and pixels) using escape sequences, system calls, or win-specific APIs.
- Logging Module — represented by logger.go, which handles logging events or errors during processing.

##### Relationships and Interactions
- The CLI (main.go) receives user inputs and invokes the image processing module.
- The image processing module handles both the conversion/resizing of images and the selection of the appropriate protocol (kitty, iterm, or sixel).
- It queries the terminal environment via the OS abstraction module to determine screen dimensions. In this, the platform-specific files (attrs_unix.go/attrs_windows.go) come into play.
- When the input file is a document type (e.g., DOCX, PDF, etc.), the tool will use LibreOffice in a sub-process to convert documents to an image or a supported intermediary format.
- Throughout the process, the logger module records progress, errors, or important events.
- Final output from the processing module is piped back to the CLI to render an image based on the user’s terminal protocol.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project divides responsibilities among different modules (CLI, image processing, logging, platform abstraction, external dependency handling).
- Modularity: Each logical component (e.g., image handling vs. OS interactions) is implemented in its own Go file which aids in maintainability.
- Extensibility: The design is open for future enhancements (for example, integrating alternative backends for document conversion or adding more terminal protocols).

##### Technologies and Frameworks
- Go language (as indicated by go.mod and the .go files).
- External tool: LibreOffice (used when processing certain document image types).
- Terminal protocols: iTerm2, Kitty, and Sixel.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI / Entry Point"]:::cli
    IPM["Image Processing Module"]:::ipm
    OSA["OS Abstraction Layer"]:::os
    LOG["Logging Module"]:::log
    EX["External Conversion (LibreOffice)"]:::ext
    CI["CI/CD Pipeline"]:::cicd

    %% Data Flow
    CLI -->|"processes input"| IPM
    IPM -->|"queries dimensions"| OSA
    OSA -->|"returns dimensions"| IPM
    IPM -->|"calls conversion"| EX
    IPM -->|"logs events"| LOG
    IPM -->|"emits encoded image"| CLI

    %% CI/CD influences the build/release process (side process)
    CI ---|"build&deploy trigger"| CLI

    %% Click Events
    click CLI "https://github.com/skardyy/ttyimg/blob/main/main.go"
    click IPM "https://github.com/skardyy/ttyimg/blob/main/images_manipulation.go"
    click OSA "https://github.com/skardyy/ttyimg/blob/main/attrs.go"
    click LOG "https://github.com/skardyy/ttyimg/blob/main/logger.go"
    click CI "https://github.com/skardyy/ttyimg/tree/main//.github/workflows"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef ipm fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef os fill:#FFFFE0,stroke:#333,stroke-width:2px;
    classDef log fill:#D3D3D3,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef ext fill:#FA8072,stroke:#333,stroke-width:2px,stroke-dasharray: 2 2;
    classDef cicd fill:#DA70D6,stroke:#333,stroke-width:2px,stroke-dasharray: 4 4;
    
    %% Annotations (Protocols handled)
    Note1["Note: Handles iTerm2, Kitty and Sixel protocols"]:::cli
    CI --- Note1
    style Note1 fill:#FFE4B5,stroke:#333,stroke-width:1px
```
