# shshemi/tabiew architecture

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

- Interactive diagram: https://gitdiagram.com/shshemi/tabiew
- Repository: https://github.com/shshemi/tabiew

## Overview

##### Project Type and Purpose
- Tabiew is a TUI application written in Rust. Its core purpose is to allow users to view and query various tabular data files (CSV, Parquet, JSON, SQLite, etc.) using features such as Vim-style keybindings, SQL querying, and fuzzy search.
- The project is structured as a monolithic, modular application that separates concerns into distinct layers: user interface, event handling/command processing, data access (readers/writers), and application core logic.

##### Analyzing the File Structure
- Top-level Files: You see configuration/build files (Cargo.toml, Cargo.lock, build.rs, .github workflows) that are standard in Rust projects.
- The src Directory: This is where the bulk of the logic resides. Key modules include:
- Core Application:
- main.rs – the entry point.
- lib.rs – exposes the library’s API for the rest of the application.
- app.rs and config.rs – responsible for initializing and managing the overall application state and configuration.
- Command-Line and Event Handling:
- args.rs – responsible for parsing command-line arguments.
- The handler subdirectory – includes modules such as action.rs, command.rs, event.rs, key.rs. These collectively process user input (keys/commands) and dispatch them appropriately.
- Data Access/Processing:
- reader/ – contains modules for reading various file types (fwf.rs for fixed-width files, sqlite.rs, mod.rs). This layer abstracts the file format-specific logic.
- writer/ – for any eventual operations that output or modify data.
- SQL and Search Operations:
- sql.rs and search.rs appear to add SQL and fuzzy search functionality, tying data processing with user queries.
- TUI Components:
- The tui subdirectory – holds UI widgets and components (command_pallete, data_frame_table, input, search_bar, status_bar, tabs, terminal, theme, etc.). This is the visual layer that interacts directly with the end-user.
- Utilities:
- The utils directory – includes helper functions and extensions (history, iter_ext, polars_ext, type_ext) to support various operations across the application.

##### Key Insights from the README
- The README confirms that Tabiew offers multiple themes, a tutorial, and detail on keyboard shortcuts. This underscores the importance of the TUI layer and command/event processing mechanics.
- It also emphasizes key user interactions (querying, filtering, ordering) which interact with the SQL and data processing layers.

a. Main Components to Include:
- Application Entry Point:
- Main (src/main.rs) which then loads configuration (src/config.rs) and initializes the application state (src/app.rs).
- Command/Event Handler:
- Modules in src/handler (action, command, event, key) that capture and interpret user input.
- TUI Module:
- Components in src/tui (terminal, command pallete, data frame table, search bar, tabs, etc.) that render the interface and interact with the handler.
- Data Processing Layer:
- Reader modules (from src/reader) that load and parse various file formats.
- The SQL module (src/sql.rs) and search module (src/search.rs) that execute queries and perform fuzzy search operations.
- Utility/Support Modules:
- Utility functions (in src/utils) and writer modules (src/writer) available across layers.

b. Relationships and Data Flow:
- User Input (via TUI) → TUI Components capture keystrokes and commands.
- TUI Components send events to the Event Handlers (handler/* modules).
- Command Handlers then call upon Core Application logic (app.rs/config.rs) as needed.
- For querying data:
- The SQL and search modules are invoked.
- Data readers (src/reader) load/parses the requested files.
- Processed data is then forwarded back to TUI Components for rendering.
- Utilities act as supporting modules that can be called from different layers.

c. Architectural Patterns and Principles:
- Layered Architecture: Separating UI, business logic, and data access.
- Modular Design: Each folder/module focuses on a single responsibility (e.g., tui, reader, handler) which makes components easily testable and replaceable.
- Event-Driven Flow: The command and event handler modules indicate an event-driven approach for user interactions.

d. Relevant Technologies & Frameworks:
- Rust as the programming language.
- Cargo for package management and building.
- Terminal UI libraries (likely leveraging Rust TUI crates, as seen via the tui/ directory).
- SQL parsing and fuzzy search implementations as part of the business logic, interacting with CSV/Parquet readers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface (UI)
    subgraph "User Interface (UI)"
        CP["Command Palette"]:::ui
        DFT["Data Frame Table"]:::ui
        IN["Input"]:::ui
        SB["Search Bar"]:::ui
        TB["Tabs"]:::ui
        TER["Terminal"]:::ui
        THM["Theme"]:::ui
    end

    %% Event/Command Handling
    subgraph "Event/Command Handling"
        ARG["Args Parsing"]:::handler
        ACT["Action Handler"]:::handler
        CMD["Command Processor"]:::handler
        EVT["Event Handler"]:::handler
        KY["Key Handler"]:::handler
    end

    %% Application Core
    subgraph "Application Core"
        MAIN["Main"]:::core
        APP["App"]:::core
        CFG["Config"]:::core
    end

    %% Data Processing Layer
    subgraph "Data Processing Layer"
        subgraph "Readers"
            FWF["Fixed-Width Reader"]:::data
            SQLR["SQLite Reader"]:::data
            RMOD["Reader Core"]:::data
        end
        subgraph "Query Processing"
            SQL["SQL Module"]:::data
            SRCH["Search Module"]:::data
        end
        WRTR["Writers"]:::data
    end

    %% Utilities
    subgraph "Utilities"
        HIST["History"]:::util
        ITER["Iterator Extensions"]:::util
        POLAR["Polars Extensions"]:::util
        TYP["Type Extensions"]:::util
    end

    %% Data Flow Arrows
    TER -->|"user_input"| KY
    KY -->|"dispatch"| EVT
    EVT -->|"forward_command"| CMD
    CMD -->|"invoke_core"| APP
    APP -->|"initiate_config"| CFG
    APP -->|"handle_query"| SQL
    APP -->|"read_file"| FWF
    APP -->|"read_file"| SQLR
    APP -->|"read_file_core"| RMOD
    APP -->|"trigger_write"| WRTR
    SQL -->|"return_results"| DFT
    SRCH -->|"return_results"| DFT

    %% Utility interactions (dashed lines)
    HIST -.-> APP
    ITER -.-> APP
    POLAR -.-> SQL
    TYP -.-> APP

    %% Click Events for Application Entry Point
    click MAIN "https://github.com/shshemi/tabiew/blob/main/src/main.rs"
    click APP "https://github.com/shshemi/tabiew/blob/main/src/app.rs"
    click CFG "https://github.com/shshemi/tabiew/blob/main/src/config.rs"

    %% Click Events for Command-Line Argument Parsing
    click ARG "https://github.com/shshemi/tabiew/blob/main/src/args.rs"

    %% Click Events for Command and Event Handling
    click ACT "https://github.com/shshemi/tabiew/blob/main/src/handler/action.rs"
    click CMD "https://github.com/shshemi/tabiew/blob/main/src/handler/command.rs"
    click EVT "https://github.com/shshemi/tabiew/blob/main/src/handler/event.rs"
    click KY "https://github.com/shshemi/tabiew/blob/main/src/handler/key.rs"

    %% Click Events for Data Access (Readers)
    click FWF "https://github.com/shshemi/tabiew/blob/main/src/reader/fwf.rs"
    click SQLR "https://github.com/shshemi/tabiew/blob/main/src/reader/sqlite.rs"
    click RMOD "https://github.com/shshemi/tabiew/blob/main/src/reader/mod.rs"

    %% Click Events for SQL and Search Processing
    click SQL "https://github.com/shshemi/tabiew/blob/main/src/sql.rs"
    click SRCH "https://github.com/shshemi/tabiew/blob/main/src/search.rs"

    %% Click Event for Writers
    click WRTR "https://github.com/shshemi/tabiew/blob/main/src/writer/mod.rs"

    %% Click Events for TUI Components
    click CP "https://github.com/shshemi/tabiew/blob/main/src/tui/command_pallete.rs"
    click DFT "https://github.com/shshemi/tabiew/blob/main/src/tui/data_frame_table.rs"
    click IN "https://github.com/shshemi/tabiew/blob/main/src/tui/input.rs"
    click SB "https://github.com/shshemi/tabiew/blob/main/src/tui/search_bar.rs"
    click TB "https://github.com/shshemi/tabiew/blob/main/src/tui/tabs.rs"
    click TER "https://github.com/shshemi/tabiew/blob/main/src/tui/terminal.rs"
    click THM "https://github.com/shshemi/tabiew/blob/main/src/tui/theme.rs"

    %% Click Events for Utility/Support Modules
    click HIST "https://github.com/shshemi/tabiew/blob/main/src/utils/history.rs"
    click ITER "https://github.com/shshemi/tabiew/blob/main/src/utils/iter_ext.rs"
    click POLAR "https://github.com/shshemi/tabiew/blob/main/src/utils/polars_ext.rs"
    click TYP "https://github.com/shshemi/tabiew/blob/main/src/utils/type_ext.rs"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#3182bd,stroke-width:2px;
    classDef handler fill:#c3f3c3,stroke:#2f855a,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef data fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px;
    classDef util fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px;
```
