# bensadeh/tailspin architecture

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

- Interactive diagram: https://gitdiagram.com/bensadeh/tailspin
- Repository: https://github.com/bensadeh/tailspin

## Overview

##### Main Components
- CLI Interface: Represented primarily by the files in src/cli (including command parsing, completions, and keyword processing). This is the entry point – it accepts command line arguments, flags (like --follow, --listen-command, and others), and options for customizing highlighting.
- Configuration & Theme Module: Shown in src/config and src/theme. These modules are responsible for reading and processing configuration files (like theme.toml) so that highlight styles and groups (e.g., dates, keywords, IP addresses) can be customized.
- Core Highlighter Logic: The heart lies in src/core. This module handles the actual log processing:
- It reads each log file line and uses various regular expressions (stored in src/core/highlighters) to detect and format parts of the log (e.g., dates, numbers, keywords).
- It includes common utilities (like normalization and splitting text) in src/core/utils and error handling in src/core/error.rs.
- Highlighter Builder: Found in src/highlighter_builder. This module aggregates built-in highlighters and possibly composes custom ones based on configuration or command-line parameters.
- Input/Output (I/O) Components: The IO part split into reading (src/io/reader) and writing/presenting (src/io/writer & src/io/presenter). The reader handles both file input and piped input (including the functionality for listening to other commands), whereas the presenter decides whether to output directly to stdout or to integrate with external utilities like the “less” pager.
- Utilities & Build Scripts: There are utility scripts (in the util directory) for generating documentation (man pages) and shell completions, which are useful for distribution and integration. Testing folders also exist to validate the core functionality.

##### Component Relationships and Data Flow
- Configuration Flow: Early in the execution path, the configuration module loads the default settings (and overrides from ~/.config/tailspin/theme.toml if provided) and passes the configuration to the core modules.
- Data Processing in the Core: The core module iterates line by line over the log file or live stream, using a series of regex-based highlighters. The highlighter builder helps by selecting the appropriate highlighters (either built-in or customized via the configuration) and applying them.
- I/O Flow: Processed (highlighted) data is handed off to the presenter. Depending on the parameters, it is either forwarded directly to stdout or piped through “less” (with navigation support such as following mode and search capabilities).
- External Dependencies: The system integrates with external tools, notably “less” (for paged display) and the manifold crate that provides underlying functionality for log highlighting.

##### Architectural Patterns & Design Principles
- Modular Separation: Components are separated into distinct modules (CLI, Core, Config, I/O, Theme). This clear, layered architecture reduces coupling.
- Pipeline/Data Flow: Highlighting is performed in a streaming pipeline – input is read, processed, and forwarded, which is ideal for log file processing.
- Extensibility: The design supports new highlighters, custom regexes, and additional configuration options without modifying the core processing loop.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        UI["User Input/CLI Invocation"]:::cli
        CLI["CLI Interface"]:::cli
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        CFG["Config Loader"]:::config
        THEME["Theme Parser"]:::config
    end

    %% Core Processing Layer
    subgraph "Processing Layer"
        CORE["Core Log Processor"]:::core
        HLBuilder["Highlighter Builder"]:::core
        Regex["Regex Highlighters & Utilities"]:::core
        CORE --- HLBuilder
        CORE --- Regex
    end

    %% I/O Layer
    subgraph "I/O Layer"
        READER["Log Reader"]:::io
        PRESENTER["Log Presenter"]:::io
        WRITER["Log Writer"]:::io
    end

    %% External Dependencies
    subgraph "External Tools"
        LESS["less Pager"]:::external
        MANIFOLD["Manifold Crate"]:::external
    end

    %% Utilities & Testing
    subgraph "Support & Testing"
        UTIL["Utility Scripts"]:::utility
        TEST["Testing Suite"]:::utility
    end

    %% Connections - Data Flow
    UI --> CLI
    CLI -->|"provides args to"| READER
    CLI -->|"initiates config"| CFG
    CLI -->|"initiates config"| THEME
    CFG --> CORE
    THEME --> CORE
    READER --> CORE
    CORE --> PRESENTER
    CORE --> WRITER
    CORE -->|"uses"| MANIFOLD
    PRESENTER -->|"pipes to"| LESS

    %% Support connections (dashed)
    UTIL --- CORE
    TEST --- CORE
    UTIL --- CLI

    %% Click Events
    click CLI "https://github.com/bensadeh/tailspin/tree/main/src/cli"
    click CFG "https://github.com/bensadeh/tailspin/tree/main/src/config"
    click THEME "https://github.com/bensadeh/tailspin/tree/main/src/theme"
    click CORE "https://github.com/bensadeh/tailspin/tree/main/src/core"
    click Regex "https://github.com/bensadeh/tailspin/tree/main/src/core/highlighters"
    click HLBuilder "https://github.com/bensadeh/tailspin/tree/main/src/highlighter_builder"
    click READER "https://github.com/bensadeh/tailspin/tree/main/src/io/reader"
    click PRESENTER "https://github.com/bensadeh/tailspin/tree/main/src/io/presenter"
    click WRITER "https://github.com/bensadeh/tailspin/tree/main/src/io/writer"
    click UTIL "https://github.com/bensadeh/tailspin/tree/main/util"
    click TEST "https://github.com/bensadeh/tailspin/tree/main/tests"

    %% Styles
    classDef cli fill:#a6cee3,stroke:#000,stroke-width:2px;
    classDef config fill:#b2df8a,stroke:#000,stroke-width:2px;
    classDef core fill:#fdbf6f,stroke:#000,stroke-width:2px;
    classDef io fill:#cab2d6,stroke:#000,stroke-width:2px;
    classDef external fill:#fb9a99,stroke:#000,stroke-width:2px;
    classDef utility fill:#ffff99,stroke:#000,stroke-width:2px;
```
