# hail-hydrant/zxc architecture

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

- Interactive diagram: https://gitdiagram.com/hail-hydrant/zxc
- Repository: https://github.com/hail-hydrant/zxc

## Overview

##### Core Components
- zxc Main Binary: The central executable that implements the proxy logic and coordinates session management.
- Communication Channels: Unix socket channels which connect the zxc binary with various user interface windows (Interceptor, History, Repeater, Addons) running inside tmux/Vim.
- User Interface:
– Interceptor Window: Displays intercepted HTTP/WebSocket messages and offers controls for forwarding, dropping, or modifying messages.
– History Window: Stores previous requests (HTTP history, full WebSocket history, etc.), operates in a read-only mode and manages logging.
– Repeater Window: Copies requests for repeating or re-sending them, including support for WebSocket repeater tasks.
– Addons Module: Integrates with third‐party tools (like ffuf and sqlmap). It shows a split view with the original request and terminal output of the addon program.
- Configuration Management: Global and local config files (TOML files, tmux configurations, and Vim plugin files) which are used to initialize and customize session behavior.
- Supporting Libraries/Modules: Multiple internal crates (like “buffer”, “mime”, “oneone”, “protocol_traits”, “zxc-derive”) implement HTTP parsing, state management, encryption, header and body handling, and various protocol-related processing.
- External Dependencies: OpenSSL for key generation/CA, build scripts (Makefile, mkscripts for CA and vim setups), and additional required binaries (ffuf, sqlmap, etc.).

##### Interactions & Data Flows
– Incoming HTTP/HTTPS/WebSocket requests from external clients hit the zxc proxy.
– Within zxc, the routing of these messages to different modules (e.g., parsing in “oneone” or “mime” modules).
– The Interceptor window (for real-time intercepted requests/responses).
– The History window (recording/logging the proxy’s transactions).
– The Repeater window (for editing and sending copied requests).
– The Addons component (for handing off requests to external command-line tools).
- That all modules communicate via a shared Unix socket channel which lines should be clearly marked as “Unix socket communication channels.”

##### Architectural Patterns and Technologies
- Modular Design & Separation of Concerns: Illustrate that the project is split into multiple Rust crates (each handling specific responsibilities such as parsing, communication, protocol handling, and configuration).
- Plugin-Based & Extensible UI: Outline how Vim (using zxc.vim) and tmux serve as the UI, with each window having dedicated keybindings and even separate configuration files (ftplugins).
- Client-Server Communication Pattern: The zxc binary effectively acts as a server (proxy) with front-end clients (the various Vim windows) connected over Unix sockets.
- Use of Configuration Files: Make sure to include components that represent global and local TOML-based configuration files, along with CA and tmux configuration files.

##### Final Checklist for the Principal Software Engineer
- Every component is clearly labeled (for example, “zxc Proxy Core”, “Interceptor UI”, “History Logger”, “Repeater”, “Addons”, and various internal libraries).
– Inbound connections flowing to the zxc binary.
- Interactions briefly (for example, “Unix socket communication”, “HTTP request parsing”, or “Configuration load”) to improve clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    external_clients["External HTTP & WebSocket Clients"]:::external

    %% Main Proxy Core
    zxc_proxy_core["zxc Proxy Core"]:::core

    %% Supporting Libraries Subgraph
    subgraph "Supporting Libraries"
        oneone["oneone (HTTP parsing)"]:::library
        mime["mime (Protocol handling)"]:::library
        buffer["buffer (Core utilities)"]:::library
        zxc_derive["zxc-derive (Derive macros)"]:::library
        protocol_traits["protocol_traits (Protocol traits)"]:::library
    end

    %% Communication Channel for Unix sockets
    unix_socket["Unix Socket Communication"]:::channels

    %% UI Modules Subgraph
    subgraph "User Interface (tmux/Vim)"
        interceptor_ui["Interceptor UI"]:::ui
        history_ui["History UI"]:::ui
        repeater_ui["Repeater UI"]:::ui
        addons_ui["Addons UI"]:::ui
    end

    %% Configuration Management
    config["Global & Local Config (TOML, Vim/tmux)"]:::config

    %% External Dependencies & Build Scripts
    external_tools["External Dependencies & Build Scripts"]:::dependency
    mkscripts_node["Setup Scripts (mkscripts)"]:::dependency
    makefile_node["Makefile"]:::dependency

    %% Connections
    external_clients -->|"incoming_requests"| zxc_proxy_core

    zxc_proxy_core -->|"parses_using"| oneone
    zxc_proxy_core -->|"handles_mime"| mime
    zxc_proxy_core -->|"utilizes"| buffer
    zxc_proxy_core -->|"applies_macros"| zxc_derive
    zxc_proxy_core -->|"uses_traits"| protocol_traits

    zxc_proxy_core -->|"sends_via_socket"| unix_socket
    unix_socket -->|"communicates_with"| interceptor_ui
    unix_socket -->|"communicates_with"| history_ui
    unix_socket -->|"communicates_with"| repeater_ui
    unix_socket -->|"communicates_with"| addons_ui

    config -- "configuration_load" --- zxc_proxy_core
    config -- "UI_customization" --- interceptor_ui
    config -- "UI_customization" --- history_ui
    config -- "UI_customization" --- repeater_ui
    config -- "UI_customization" --- addons_ui

    zxc_proxy_core -->|"triggers_addon_commands"| external_tools
    external_tools -->|"scripts"| mkscripts_node
    external_tools -->|"build"| makefile_node

    addons_ui -->|"hand-off_to_tools"| external_tools

    %% Click Events
    click zxc_proxy_core "https://github.com/hail-hydrant/zxc/blob/main/zxc/src/main.rs"
    click unix_socket "https://github.com/hail-hydrant/zxc/tree/main/zxc/src/io/unix_sock/"
    click interceptor_ui "https://github.com/hail-hydrant/zxc/tree/main/zxc/src/interceptor/"
    click history_ui "https://github.com/hail-hydrant/zxc/tree/main/zxc/src/history/"
    click repeater_ui "https://github.com/hail-hydrant/zxc/tree/main/zxc/src/repeater/"
    click addons_ui "https://github.com/hail-hydrant/zxc/tree/main/zxc/src/addons/"
    click config "https://github.com/hail-hydrant/zxc/tree/main/zxc/src/config/"
    click oneone "https://github.com/hail-hydrant/zxc/tree/main/oneone/"
    click mime "https://github.com/hail-hydrant/zxc/tree/main/mime/"
    click buffer "https://github.com/hail-hydrant/zxc/tree/main/buffer/"
    click zxc_derive "https://github.com/hail-hydrant/zxc/tree/main/zxc-derive/"
    click protocol_traits "https://github.com/hail-hydrant/zxc/tree/main/protocol_traits/"
    click mkscripts_node "https://github.com/hail-hydrant/zxc/tree/main/mkscripts/"
    click makefile_node "https://github.com/hail-hydrant/zxc/tree/main/Makefile"

    %% Styles
    classDef core fill:#ffcccc,stroke:#cc0000,stroke-width:2px,color:#000;
    classDef ui fill:#cceeff,stroke:#0099cc,stroke-width:2px,color:#000;
    classDef library fill:#ddffdd,stroke:#66cc66,stroke-width:2px,color:#000;
    classDef config fill:#ffffcc,stroke:#cccc00,stroke-width:2px,color:#000;
    classDef channels fill:#e0e0e0,stroke:#808080,stroke-width:2px,color:#000;
    classDef external fill:#ffe6f2,stroke:#ff66a3,stroke-width:2px,color:#000;
    classDef dependency fill:#ffe6e6,stroke:#ff6666,stroke-width:2px,color:#000;
```
