# sgrumley/gotex architecture

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

## Overview

##### Project Type and Purpose
- Gotex is a cross-platform TUI test explorer for Go projects, aimed at simplifying test navigation and execution directly from the terminal.
- The project’s purpose is clearly to provide an interactive user interface (TUI) for running and managing Go tests, incorporating features like fuzzy search, keybindings (Vim-like), test discovery, and result management.

##### File Structure
- The project has a clear separation between the command-line entry point and its internal logic:
- "cmd/gotex/main.go" – This file is the main application entry point which bootstraps and starts the TUI application.
- The "internal" directory contains the UI components. For example:
- internal/components/app.go, config_modal.go, console_panel.go, events.go, etc. Each file here likely represents a different panel or widget within the TUI (e.g., search modal, test tree panel, results panel, and keybinding setup).
- The "pkg" directory hosts various libraries and utilities:
- pkg/config – Handles configuration (with a default YAML file included).
- pkg/finder – Contains modules for discovering tests, files, functions etc. (includes logic for fuzzy search and test package discovery).
- pkg/runner – Contains logic for running tests.
- pkg/logging and pkg/ansi – Likely provide logging utilities and ANSI code handling for terminal formatting.
- Auxiliary files include the Dockerfile (for containerization), testdata (for testing purposes), and configuration files.

##### README Insights
- The README makes it clear that Gotex provides a TUI with Vim-like keybindings, fuzzy search, and test control actions.
- Dependencies mentioned: it uses the [tview](https://github.com/rivo/tview) library for building the TUI.
- The installation and usage instructions indicate that the application is started from within a Go project directory, suggesting it interacts with the Go test ecosystem.

a. Main Components:
- TUI Application Core: Represents the main application logic (cmd/gotex/main.go) that bootstraps the interface.
- UI Components: Under internal/components, include panels for configuration (config_modal), test results (results_panel), test tree (testTree_panel), console (console_panel), and help (help_panel).
- Service/Logic Layer: Provided by packages such as:
- pkg/config – Manages configuration settings.
- pkg/finder – Discovers test files, functions, and Go packages.
- pkg/runner – Executes the tests and gathers results.
- pkg/logging – Handles logging across the application.
- pkg/ansi – Manages ANSI codes for terminal output.

b. Relationships and Interactions:
- The TUI Application Core initializes and orchestrates the UI components.
- UI components (panels) display dynamic information (test lists, search results, logs) by invoking functions from pkg/finder, pkg/runner, and pkg/config.
- User actions (e.g., pressing a key to run tests) are captured by the TUI and sent to the runner (pkg/runner) to execute tests.
- Configuration is loaded via pkg/config (possibly reading a YAML file) and then injected into relevant parts of the system.
- Logging and ANSI handling are utilities that support both the UI and backend processes.

c. Architectural Patterns/Design Principles:
- Separation of Concerns: Clear boundary between the UI (internal/components) and the backend logic (pkg/*). This separation enhances maintainability.
- Modular Design: Each aspect (test discovery, configuration, test execution) is handled by its own package/module.
- MVC-like Approach: The TUI (view) interacts with underlying packages (controllers/services) for business logic, while data (the test cases and configurations) are managed separately.

d. Specify Relevant Technologies/Frameworks:
- Go language (with modules as seen in go.mod and go.sum).
- tview library for TUI.
- YAML configuration (pkg/config).
- Standard Go testing mechanisms supported by pkg/finder and pkg/runner.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Interaction
    Terminal["Terminal Input / tview Library"]:::external

    %% Entry Point
    Core["TUI Application Core (main.go)"]:::core

    %% UI Layer
    subgraph "UI Layer"
        UIContainer["Main UI Container (app.go)"]:::ui
        ConfigModal["Configuration Modal (config_modal.go)"]:::ui
        ConsolePanel["Console Panel (console_panel.go)"]:::ui
        HelpPanel["Help Panel (help_panel.go)"]:::ui
        ResultsPanel["Results Panel (results_panel.go)"]:::ui
        SearchModal["Search Modal (search_modal.go)"]:::ui
        TestTreePanel["Test Tree Panel (testTree_panel.go)"]:::ui
        KeyEvents["Keybindings & Events Handling (keybindings.go & events.go)"]:::ui
    end

    %% Service Layer
    subgraph "Service Layer"
        ConfigService["Configuration Service (config.go/default.yaml)"]:::service
        FinderService["Test Discovery Service (pkg/finder)"]:::service
        RunnerService["Test Runner Service (runner.go)"]:::service
        LoggingUtil["Logging Utility (logger.go)"]:::service
        ANSIUtil["ANSI Formatting Utility (ansi.go)"]:::service
    end

    %% Connections: External to Core
    Terminal -->|"input"| Core

    %% Core initializes UI and Services
    Core -->|"initializes"| UIContainer
    Core -->|"loads"| ConfigService

    %% UI Container propagates configuration and events
    UIContainer -->|"opens"| ConfigModal
    UIContainer -->|"displays"| ConsolePanel
    UIContainer -->|"shows"| HelpPanel
    UIContainer -->|"renders"| ResultsPanel
    UIContainer -->|"invokes"| SearchModal
    UIContainer -->|"builds"| TestTreePanel
    UIContainer -->|"handles"| KeyEvents

    %% UI Panels interact with Services
    ConfigModal -->|"loadConfig"| ConfigService

    TestTreePanel -->|"discoverTests"| FinderService
    SearchModal -->|"searchTests"| FinderService

    KeyEvents -->|"triggerTests"| RunnerService

    %% Runner interacts with utilities
    RunnerService -->|"logOutput"| LoggingUtil
    RunnerService -->|"formatOutput"| ANSIUtil

    %% UI panels display outputs
    ConsolePanel -->|"displayLogs"| LoggingUtil
    ResultsPanel -->|"displayResults"| RunnerService

    %% Styling
    classDef external fill:#f8d7da,stroke:#dc3545,stroke-width:2px,color:#000;
    classDef core fill:#fff3cd,stroke:#ffc107,stroke-width:2px,color:#000;
    classDef ui fill:#cce5ff,stroke:#2a9df4,stroke-width:2px,color:#000;
    classDef service fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#000;

    %% Click Events
    click Core "https://github.com/sgrumley/gotex/blob/master/cmd/gotex/main.go"
    click UIContainer "https://github.com/sgrumley/gotex/blob/master/internal/components/app.go"
    click ConfigModal "https://github.com/sgrumley/gotex/blob/master/internal/components/config_modal.go"
    click ConsolePanel "https://github.com/sgrumley/gotex/blob/master/internal/components/console_panel.go"
    click HelpPanel "https://github.com/sgrumley/gotex/blob/master/internal/components/help_panel.go"
    click ResultsPanel "https://github.com/sgrumley/gotex/blob/master/internal/components/results_panel.go"
    click SearchModal "https://github.com/sgrumley/gotex/blob/master/internal/components/search_modal.go"
    click TestTreePanel "https://github.com/sgrumley/gotex/blob/master/internal/components/testTree_panel.go"
    click KeyEvents "https://github.com/sgrumley/gotex/blob/master/internal/components/keybindings.go"
    click KeyEvents "https://github.com/sgrumley/gotex/blob/master/internal/components/events.go"
    click ConfigService "https://github.com/sgrumley/gotex/blob/master/pkg/config/config.go"
    click ConfigService "https://github.com/sgrumley/gotex/blob/master/pkg/config/default.yaml"
    click FinderService "https://github.com/sgrumley/gotex/tree/master/pkg/finder"
    click RunnerService "https://github.com/sgrumley/gotex/blob/master/pkg/runner/runner.go"
    click LoggingUtil "https://github.com/sgrumley/gotex/blob/master/pkg/logging/logger.go"
    click ANSIUtil "https://github.com/sgrumley/gotex/blob/master/pkg/ansi/ansi.go"
```
