# jaysym-ai/qlood-cli architecture

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

- Interactive diagram: https://gitdiagram.com/jaysym-ai/qlood-cli
- Repository: https://github.com/jaysym-ai/qlood-cli

## Overview

##### Project Type & Purpose
- QLOOD-CLI is a Node.js–based command-line application (CLI) that wraps and orchestrates the AugmentCode (Auggie) CLI to provide AI-driven end-to-end testing. It provides a text-based user interface (TUI), workflow management, Playwright-driven browser automation, and result storage for success/warning/error cases.

##### File Structure Analysis
- bin/qlood.js: the npm “bin” entrypoint for the CLI.
- src/cli: TUI helpers (spinner, update notifications).
- src/commands: individual CLI commands (clean, review, etc.) wired into the TUI command parser.
- src/tui: TUI framework: adapters (for Auggie), event loop, key mappings, layout, rendering, state management.
- src/auggie-integration.js & src/auggie-stream.js: modules that spawn and manage the Auggie CLI process, feed it prompts, parse output streams.
- src/project.js / config.js / metrics.js / debug.js: core services (project context, configuration, telemetry, logging).
- src/workflows.js & src/prompts: workflow engine and pre-made AI prompts.
- ./.qlood (runtime folder, not in git): stores workflows and test results.

##### README Insights
- Orchestrates multiple Auggie runs with pre-prompted instructions.
- Launches headless Playwright to test the app and capture screenshots.
- Provides a TUI for listing/adding/updating/deleting workflows.
- Persists results to ./.qlood/results grouped by success, warning, error.
- Requires Node.js 18+, external Auggie CLI auth, optional environment credentials.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::external

    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        Entrypoint["bin/qlood.js\n(CLI Entrypoint)"]:::internal
        Dispatcher["Command Parser & Dispatcher\n(src/commands)"]:::internal
        subgraph "TUI Helpers"
            direction TB
            Spinner["spinner.js"]:::internal
            UpdateNotifier["update.js"]:::internal
        end
        subgraph "TUI Framework"
            direction TB
            TUICore["src/tui.js"]:::internal
            Adapters["src/tui/adapters/auggie.js"]:::internal
            Events["src/tui/events.js"]:::internal
            Keymap["src/tui/keymap.js"]:::internal
            Layout["src/tui/layout.js"]:::internal
            Render["src/tui/render.js"]:::internal
            State["src/tui/state.js"]:::internal
        end
    end

    %% Core Services
    subgraph "Core Services"
        direction TB
        ProjectCtx["src/project.js"]:::internal
        ConfigSvc["src/config.js"]:::internal
        MetricsSvc["src/metrics.js"]:::internal
        DebugSvc["src/debug.js"]:::internal
    end

    %% Workflow & Prompting
    subgraph "Workflow & Prompts"
        direction TB
        WorkflowEngine["src/workflows.js\n(Workflow Engine)"]:::internal
        subgraph "Prompt Manager"
            direction TB
            Prompts["src/prompts/"]:::internal
        end
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        AuggieInt["src/auggie-integration.js\n(Auggie Integration)"]:::internal
        StreamParser["src/auggie-stream.js\n(Stream Parser)"]:::internal
        PlaywrightModule["Playwright Module"]:::external
    end

    %% External Processes
    subgraph "External Processes"
        direction TB
        AuggieCLI["Auggie CLI"]:::external
        PlaywrightProc["Playwright"]:::external
    end

    %% Data Store
    subgraph "Local Storage"
        direction TB
        QloodFS[".qlood/\n(workflows & results)"]:::datastore
    end

    %% Connections
    User -->|"invokes"| Entrypoint
    Entrypoint --> Dispatcher
    Dispatcher --> Spinner
    Dispatcher --> UpdateNotifier
    Dispatcher --> TUICore
    Dispatcher -->|"loads commands"| Dispatcher
    TUICore --> Adapters
    TUICore --> Events
    TUICore --> Keymap
    TUICore --> Layout
    TUICore --> Render
    TUICore --> State
    Dispatcher -->|"handles command"| WorkflowEngine
    WorkflowEngine --> Prompts
    WorkflowEngine --> AuggieInt
    AuggieInt -->|"spawn"| AuggieCLI
    AuggieCLI -->|"stream I/O"| AuggieInt
    AuggieInt --> StreamParser
    WorkflowEngine --> PlaywrightModule
    PlaywrightModule -->|"execute"| PlaywrightProc
    AuggieInt -->|"writes results"| QloodFS
    PlaywrightModule -->|"writes screenshots"| QloodFS
    WorkflowEngine --> ProjectCtx
    Entrypoint --> ConfigSvc
    Entrypoint --> MetricsSvc
    Entrypoint --> DebugSvc
    AuggieInt --> MetricsSvc
    PlaywrightModule --> MetricsSvc

    %% Click Events
    click Entrypoint "https://github.com/jaysym-ai/qlood-cli/blob/main/bin/qlood.js"
    click Dispatcher "https://github.com/jaysym-ai/qlood-cli/tree/main/src/commands/"
    click Spinner "https://github.com/jaysym-ai/qlood-cli/blob/main/src/cli/spinner.js"
    click UpdateNotifier "https://github.com/jaysym-ai/qlood-cli/blob/main/src/cli/update.js"
    click TUICore "https://github.com/jaysym-ai/qlood-cli/blob/main/src/tui.js"
    click Adapters "https://github.com/jaysym-ai/qlood-cli/blob/main/src/tui/adapters/auggie.js"
    click Events "https://github.com/jaysym-ai/qlood-cli/blob/main/src/tui/events.js"
    click Keymap "https://github.com/jaysym-ai/qlood-cli/blob/main/src/tui/keymap.js"
    click Layout "https://github.com/jaysym-ai/qlood-cli/blob/main/src/tui/layout.js"
    click Render "https://github.com/jaysym-ai/qlood-cli/blob/main/src/tui/render.js"
    click State "https://github.com/jaysym-ai/qlood-cli/blob/main/src/tui/state.js"
    click WorkflowEngine "https://github.com/jaysym-ai/qlood-cli/blob/main/src/workflows.js"
    click Prompts "https://github.com/jaysym-ai/qlood-cli/tree/main/src/prompts/"
    click AuggieInt "https://github.com/jaysym-ai/qlood-cli/blob/main/src/auggie-integration.js"
    click StreamParser "https://github.com/jaysym-ai/qlood-cli/blob/main/src/auggie-stream.js"
    click ConfigSvc "https://github.com/jaysym-ai/qlood-cli/blob/main/src/config.js"
    click MetricsSvc "https://github.com/jaysym-ai/qlood-cli/blob/main/src/metrics.js"
    click ProjectCtx "https://github.com/jaysym-ai/qlood-cli/blob/main/src/project.js"
    click DebugSvc "https://github.com/jaysym-ai/qlood-cli/blob/main/src/debug.js"

    %% Styles
    classDef internal fill:#bbeeff,stroke:#3399ff,color:#000
    classDef external fill:#bbffbb,stroke:#33aa33,color:#000
    classDef datastore fill:#ffeb99,stroke:#ffcc00,color:#000
```
