# npiv/chatblade architecture

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

## Overview

##### Main Components
- CLI Frontend: This is the user interface that accepts command-line arguments and piped input. It is represented by files such as chatblade/__main__.py and chatblade/cli.py.
- Chat Engine: Core functionality for building the ChatGPT queries is in chatblade/chat.py. This module is responsible for formatting the user’s request and calling the OpenAI API.
- Session Management: Managed by chatblade/session.py and chatblade/storage.py. These components save and retrieve conversation data, enabling session-based interactions (e.g., the “-S” / “-l” functionalities).
- Response Processing: Modules like chatblade/parser.py and chatblade/printer.py handle formatting, JSON extraction, and Markdown presentation of responses.
- Error Handling & Utilities: chatblade/errors.py and chatblade/utils.py support robust error processing and auxiliary tasks.
- External API Integration: Although not a module within Chatblade directly, the tool interacts with OpenAI’s ChatGPT via REST calls. Also, environment variables and configuration management (e.g., OpenAI API keys, Azure settings) are crucial here.

##### Component Relationships and Interactions
- User Input → CLI Frontend:
- The CLI interface (via __main__.py) captures input (parameters, piped data) and passes it to the command parser (cli.py).
- CLI Frontend → Chat Engine:
- Chat Engine → External OpenAI API:
- The chat module forms the API request using provided arguments (like model selection with -c, system prompt with -p, etc.) and sends it to ChatGPT.
- API Response → Response Processing:
- The response from OpenAI is then passed to parser.py to extract or format content (raw text, Markdown, or JSON as specified by the user).
- Printer.py then handles how this output is presented to the terminal.
- Session Management:
- For each conversation, chatblade/session.py uses storage.py to save or recall sessions (identified by “-S” or “-l”), keeping track of the conversation state.
- Error Handling:
- Throughout these processes, errors are managed by errors.py ensuring consistent messaging and fallback if issues occur.

##### Architectural Patterns and Design Principles
- Modular Design: The project is split into logical, single-purpose modules for CLI interaction, chat logic, session handling, and formatting.
- Separation of Concerns: Each component (input handling, API interaction, session management, formatting) is standalone, making the system easier to maintain.
- Extensibility: The use (and loading) of custom prompt files and support for various session operations shows a design that anticipates future extension.

##### Relevant Technologies and Libraries
- Python Modules and Packaging: Evident from the project’s layout (setup.py, pyproject.toml, etc.), following Python’s standard packaging.
- OpenAI’s API: The primary external dependency used to send/receive data from ChatGPT.
- CLI Utilities: Likely using argparse or similar libraries in cli.py for handling command-line options.
- Integration with Tools: Mention of piping, streaming, and possible integration with JSON formatting (e.g., piping to jq).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    userInput["User Input"]:::user
    terminal["Terminal Output"]:::output
    openai["OpenAI API"]:::external

    %% CLI Frontend Subgraph
    subgraph "CLI Frontend"
        cliMain["__main__.py"]:::cli
        cliParser["cli.py"]:::cli
    end

    %% Chat Engine Node
    chatEngine["chat.py"]:::chat

    %% Session Management Subgraph
    subgraph "Session Management"
        sessionMgmt["session.py"]:::session
        storage["storage.py"]:::session
    end

    %% Response Processing Subgraph
    subgraph "Response Processing"
        parser["parser.py"]:::response
        printer["printer.py"]:::response
    end

    %% Error Handling & Utilities Subgraph
    subgraph "Error Handling & Utilities"
        errors["errors.py"]:::error
        utils["utils.py"]:::error
    end

    %% Flow Connections
    userInput --> cliMain
    cliMain --> cliParser
    cliParser --> chatEngine
    chatEngine -- "API_Request" --> openai
    openai -- "API_Response" --> chatEngine
    chatEngine --> parser
    parser --> printer
    printer --> terminal
    chatEngine --> sessionMgmt
    sessionMgmt --> storage

    %% Error Handling dashed connections
    cliParser -.-> errors
    chatEngine -.-> errors
    sessionMgmt -.-> errors
    parser -.-> errors

    %% Click Events
    click cliMain "https://github.com/npiv/chatblade/blob/main/chatblade/__main__.py"
    click cliParser "https://github.com/npiv/chatblade/blob/main/chatblade/cli.py"
    click chatEngine "https://github.com/npiv/chatblade/blob/main/chatblade/chat.py"
    click sessionMgmt "https://github.com/npiv/chatblade/blob/main/chatblade/session.py"
    click storage "https://github.com/npiv/chatblade/blob/main/chatblade/storage.py"
    click parser "https://github.com/npiv/chatblade/blob/main/chatblade/parser.py"
    click printer "https://github.com/npiv/chatblade/blob/main/chatblade/printer.py"
    click errors "https://github.com/npiv/chatblade/blob/main/chatblade/errors.py"
    click utils "https://github.com/npiv/chatblade/blob/main/chatblade/utils.py"

    %% Styles
    classDef user fill:#FFF3E0,stroke:#D84315,stroke-width:2px;
    classDef cli fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef chat fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef session fill:#FFE082,stroke:#FF6F00,stroke-width:2px;
    classDef response fill:#F8BBD0,stroke:#AD1457,stroke-width:2px;
    classDef error fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef external fill:#E0E0E0,stroke:#424242,stroke-width:2px;
    classDef output fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
```
