# karthink/gptel architecture

> Architecture diagram of the GitHub repository karthink/gptel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karthink/gptel
- Repository: https://github.com/karthink/gptel

## Overview

##### Main System Components

The system can be divided into these primary components:

a) Core Components:
- Request Handler (gptel.el)
- Backend Management System
- Response Processing System
- Context Management System

b) Backend Adapters:
- OpenAI/ChatGPT (gptel-openai.el)
- Anthropic/Claude (gptel-anthropic.el)
- Google/Gemini (gptel-gemini.el)
- Local LLMs (gptel-ollama.el, gptel-privategpt.el)
- Other API-based services (gptel-kagi.el)

c) UI/Integration Components:
- Buffer Management
- Transient Menu Interface (gptel-transient.el)
- Org Mode Integration (gptel-org.el)
- Text Rewriting System (gptel-rewrite.el)

**┌─────────────────────────────────────────────────────────────────┐**
- Emacs Environment                         │
- ┌─────────────────────────────────────────────────────────┐   │
- gptel Core System                     │   │
- ┌─────────────┐ ┌──────────────┐  ┌────────────────┐  │   │
- Request   │ │   Backend    │  │    Response    │  │   │
- Handler   │ │   Manager    │  │   Processor    │  │   │
- ┘ └──────────────┘  └────────────────┘  │   │
- ▲              ▲                  ▲           │   │
- ┼──────────────┼──────────────────┼───────────┘   │

- ┌──────────┼──────────────┼──────────────────┼───────────┐   │
- ▼              ▼                   ▼          │   │
- ┌─────────────────────────────────────────────────┐  │   │
- Backend Adapters                   │  │   │
- ┌─────────┐ ┌─────────┐ ┌─────────────────┐   │  │   │
- OpenAI  │ │ Claude  │ │ Local LLM       │   │  │   │
- ┘ └─────────┘ └─────────────────┘   │  │   │
- ┘  │   │
- ▲                             │   │
- ┼─────────────────────────────┘   │

- ┌────────────────────────────────────────────────────────┐  │
- UI Components                        │  │
- ┌──────────┐  ┌───────────┐  ┌────────────────────┐  │  │
- Transient│  │ Org Mode  │  │ Buffer Management  │  │  │
- Menu    │  │Integration│  │                    │  │  │
- ┘  └───────────┘  └────────────────────┘  │  │
- ┘  │
- ┘

##### Key Relationships to Highlight

a) Data Flow:
- User Input → UI Components → Request Handler
- Request Handler → Backend Manager → Specific Backend
- Backend → Response Processor → Buffer Management

b) Integration Points:
- Backend Manager ↔ Multiple Backend Adapters
- Core System ↔ UI Components
- Org Mode Integration ↔ Buffer Management

##### Important Implementation Details

- Async nature of the system
- Streaming response capability
- Text property-based response tracking
- Context management system
- File/media handling capability

##### External Dependencies

- Connections to external APIs
- Curl/url-retrieve alternatives
- Integration with Emacs' native systems

##### The context management system's capabilities

This will provide a clear understanding of how gptel integrates with Emacs while maintaining a clean separation between its core functionality, backend adapters, and UI components.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph EmacsSys["Emacs Environment"]
        subgraph CoreSystem["Core System"]
            ReqHandler["Request Handler"]:::core
            BackendMgr["Backend Manager"]:::core
            RespProc["Response Processor"]:::core
            ContextMgr["Context Management"]:::core
            HTTPReq["HTTP Request System"]:::core
        end

        subgraph BackendAdapters["Backend Adapters"]
            OpenAI["OpenAI/ChatGPT"]:::backend
            Claude["Anthropic/Claude"]:::backend
            Gemini["Google/Gemini"]:::backend
            subgraph LocalLLMs["Local LLM Services"]
                Ollama["Ollama"]:::backend
                PrivateGPT["PrivateGPT"]:::backend
            end
            Kagi["Kagi"]:::backend
        end

        subgraph UIComponents["UI Components"]
            BufferMgmt["Buffer Management"]:::ui
            TransientMenu["Transient Menu"]:::ui
            OrgMode["Org Mode Integration"]:::ui
            Rewrite["Text Rewriting"]:::ui
        end

        %% Core System Relationships
        ReqHandler --> BackendMgr
        BackendMgr --> HTTPReq
        HTTPReq --> RespProc
        ContextMgr --> ReqHandler
        
        %% Backend Connections
        BackendMgr --> OpenAI
        BackendMgr --> Claude
        BackendMgr --> Gemini
        BackendMgr --> Ollama
        BackendMgr --> PrivateGPT
        BackendMgr --> Kagi
        
        %% UI Integration
        UIComponents --> ReqHandler
        RespProc --> BufferMgmt
        
        %% Async Response Flow
        OpenAI & Claude & Gemini & Ollama & PrivateGPT & Kagi --> RespProc
    end

    %% Styling
    classDef core fill:#a8d1f0,stroke:#333,stroke-width:2px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:2px
    classDef ui fill:#FFB347,stroke:#333,stroke-width:2px

    %% Click Events
    click ReqHandler "https://github.com/karthink/gptel/blob/master/gptel.el"
    click ContextMgr "https://github.com/karthink/gptel/blob/master/gptel-context.el"
    click HTTPReq "https://github.com/karthink/gptel/blob/master/gptel-curl.el"
    click OpenAI "https://github.com/karthink/gptel/blob/master/gptel-openai.el"
    click Claude "https://github.com/karthink/gptel/blob/master/gptel-anthropic.el"
    click Gemini "https://github.com/karthink/gptel/blob/master/gptel-gemini.el"
    click Ollama "https://github.com/karthink/gptel/blob/master/gptel-ollama.el"
    click PrivateGPT "https://github.com/karthink/gptel/blob/master/gptel-privategpt.el"
    click Kagi "https://github.com/karthink/gptel/blob/master/gptel-kagi.el"
    click TransientMenu "https://github.com/karthink/gptel/blob/master/gptel-transient.el"
    click OrgMode "https://github.com/karthink/gptel/blob/master/gptel-org.el"
    click Rewrite "https://github.com/karthink/gptel/blob/master/gptel-rewrite.el"
```
