# h-ohsaki/chatgpt-el architecture

> Architecture diagram of the GitHub repository h-ohsaki/chatgpt-el, 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/h-ohsaki/chatgpt-el
- Repository: https://github.com/h-ohsaki/chatgpt-el

## Overview

##### Main Components
- Emacs Client:
- chatgpt.el (and optionally llama.el) are the Emacs Lisp modules that manage user interaction.
- These modules define keybindings (e.g., C-c q for submitting queries and C-c Q for inserting responses) and handle the flow of query text/response within Emacs.
- Node.js Script Backend:
- The “chatgpt” script is built on Node.js and uses Puppeteer to control the browser.
- This component also harnesses helper modules like html-to-text to process HTML responses from the AI website.
- Browser Component:
- A CDP-enabled Chromium/Chrome browser instance running with remote debugging (typically on port 9000) that renders the ChatGPT/Gemini/Claude interface.
- External AI Services:
- The actual ChatGPT, Gemini, Claude, or DeepSeek pages that the browser visits to get responses.
- (Optional) Logging/Configuration:
- Although minimal in the file structure, there is a directory “screenshot” (and an “overview.dit” file) that may serve as additional documentation or debugging aids.

##### Relationships and Data Flow
- The Emacs client initiates a query (by capturing ergonomically defined key events) and forwards it to the Node.js script.
- The Node.js script (using Puppeteer) connects to the running browser instance via the CDP, navigates to the appropriate AI service page, and submits the query.
- The AI service provides a reply which is captured by the Node.js process.
- Processed data (possibly converting from HTML to text) is sent back to Emacs to be displayed or inserted in the current buffer.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The Emacs Lisp and Node.js components are neatly divided. Emacs handles UI/interaction, while Node.js handles browser automation and data processing.
- Remote Control Pattern: The Node.js script remotely controls the browser using CDP to simulate user interactions.
- Modular Integration: External dependencies (Puppeteer, html-to-text) and configurable runtime parameters (e.g., remote debugging port) are clearly delineated.
- Lightweight and Extensible: The code structure allows flexibility (for example, alternative AI backends via command line options like “-e gemini” or “-e claude”).

##### Relevant Technologies and Frameworks
- Emacs Lisp for the client-side integration.
- Node.js, Puppeteer for remote browser control via CDP.
- Chromium/Chrome for hosting the AI service webpage.
- HTML-to-text for processing service responses.
- The file “overview.dit” and various screenshots provide auxiliary documentation for visual design elements.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Emacs Client Subgraph
    subgraph "Emacs Client"
        EM1("chatgpt.el"):::client
        EM2("llama.el"):::client
    end

    %% Node.js Backend
    SERVER("Node.js Script - chatgpt"):::backend

    %% Browser Component
    BROWSER("Chromium/Chrome with CDP (port 9000)"):::browser

    %% External AI Service
    AI("External AI Service (ChatGPT/Gemini/Claude/DeepSeek)"):::external

    %% Logging/Documentation Subgraph
    subgraph "Logging/Documentation"
        LOG1("overview.dit"):::logging
        LOG2("screenshot"):::logging
    end

    %% Data Flows (vertical)
    EM1 -->|"QuerySubmission"| SERVER
    EM2 -->|"QuerySubmission"| SERVER
    SERVER -->|"CDPCommand"| BROWSER
    BROWSER -->|"NavigateQuery"| AI
    AI -->|"SendResponse"| BROWSER
    BROWSER -->|"ForwardResponse"| SERVER
    SERVER -->|"InsertResponse"| EM1
    SERVER -->|"InsertResponse"| EM2

    %% Click Events
    click EM1 "https://github.com/h-ohsaki/chatgpt-el/blob/master/chatgpt.el"
    click EM2 "https://github.com/h-ohsaki/chatgpt-el/blob/master/llama.el"
    click SERVER "https://github.com/h-ohsaki/chatgpt-el/tree/master/chatgpt"
    click LOG1 "https://github.com/h-ohsaki/chatgpt-el/blob/master/overview.dit"
    click LOG2 "https://github.com/h-ohsaki/chatgpt-el/tree/master/screenshot"

    %% Styles
    classDef client fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef backend fill:#C1F7AE,stroke:#333,stroke-width:2px;
    classDef browser fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef external fill:#D1B2FF,stroke:#333,stroke-width:2px;
    classDef logging fill:#F2D7D5,stroke:#333,stroke-width:2px;
```
