# aandrew-me/tgpt architecture

> Architecture diagram of the GitHub repository aandrew-me/tgpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aandrew-me/tgpt
- Repository: https://github.com/aandrew-me/tgpt

## Overview

##### Project type and purpose
- This is a Go-based, cross-platform, terminal CLI tool (“tgpt”) that lets users interact with AI text/chat providers and image-generation providers from their shell.
- The README describes installation, available AI/image providers, proxy support, and general usage—confirming it’s a full-featured CLI application with a plugin-style architecture for different back-end services.

##### File structure
- Top-level files
- main.go: CLI entrypoint and command dispatch
- go.mod/go.sum, build.sh, install scripts, LICENSE, README
- Directories under src/
- bubbletea: UI layer (TUI using bubbletea framework)
- client: core HTTP client and orchestration logic
- helper, utils: miscellaneous helper functions/utilities
- structs: shared data-type definitions (requests, responses)
- providers: registry and per-provider implementations for text/chat
- imagegen: image generation module and its providers (arta, pollinations)
- md/: documentation on providers and usage
- config files: tgpt.json, version.txt

##### README for additional insights
- Emphasizes provider-based design—users can choose from multiple AI or image providers
- Proxy support via environment or config file
- tUI element (bubbletea) for interactive sessions

##### Main components and interactions
a. Components
1. CLI Entrypoint (main.go & Cobra or flag parsing)
2. TUI Layer (bubbletea module)
3. Command/Orchestration Layer (client package)
4. Provider Registry (providers/providers.go)
5. Text/Chat Providers (each src/providers/*)
6. Image Generation Layer (imagegen package + its sub-providers)
7. Shared Data Models (structs package)
8. Utilities & Helpers (utils, helper packages)
9. Configuration Store (proxy.txt, tgpt.json, environment variables)
10. External HTTP Services (OpenAI, Gemini, Pollinations, etc.)
b. Relationships & Data Flows
- User types a command → CLI Entrypoint → passes arguments to TUI or client
- TUI calls orchestration layer when needed (e.g., interactive chat)
- Orchestration layer consults config (proxy, API keys) → selects appropriate Provider via Provider Registry
- Invokes specific Provider implementation → makes HTTP request to external AI/Image service → receives response
- Response marshaled into shared structs → passed back up to TUI or printed to stdout
- ImageGen module follows similar path for image requests
c. Architectural patterns & principles
- Plugin/Factory pattern for providers: centralized registry dynamically instantiates provider implementations
- Layered modular design: UI → Orchestration → Providers → External API
- Separation of concerns: Raw HTTP client code isolated in client package, business logic in providers, UI in bubbletea
- Configuration abstraction: supports environment variables and config files
d. Key technologies/libraries
- Go modules (go.mod)
- Bubbletea TUI framework (github.com/charmbracelet/bubbletea)
- HTTP client (net/http under client package)
- JSON/YAML parsing for config
- Build & install scripts (build.sh, install-win.ps1)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User (CLI)"]:::external
    Main["CLI Entrypoint<br>(main.go)"]:::internal
    TUI["TUI Layer<br>(bubbletea)"]:::internal
    Client["Orchestration Layer<br>(client)"]:::internal
    Config["Configuration Store<br>(tgpt.json, env)"]:::config
    Structs["Shared Models<br>(structs)"]:::internal
    Utils["Utilities<br>(utils)"]:::internal
    Helper["Helpers<br>(helper)"]:::internal
    Stdout["Stdout Output"]:::external

    %% Providers Cluster
    subgraph "Providers"
        PR["Provider Registry<br>(providers.go)"]:::internal
        subgraph "Text/Chat Providers"
            DS["DeepSeek"]:::internal
            DDG["DuckDuckGo"]:::internal
            GEM["Gemini"]:::internal
            GROQ["GROQ"]:::internal
            ISO["Isou"]:::internal
            KIM["Kimi"]:::internal
            KOB["KoboldAI"]:::internal
            OLL["Ollama"]:::internal
            OPN["OpenAI"]:::internal
            PHI["Phind"]:::internal
            POL_T["Pollinations (text)"]:::internal
            SKY["Sky"]:::internal
        end
        subgraph "Image Generation Providers"
            IMGCORE["ImageGen Core<br>(imagegen)"]:::internal
            ARTA["Arta"]:::internal
            POL_I["Pollinations (image)"]:::internal
        end
    end

    %% External Services
    subgraph "External Services"
        E_OPENAI["OpenAI API"]:::external
        E_GEMINI["Gemini API"]:::external
        E_POLL_IMG["Pollinations Image API"]:::external
    end

    %% Build & Install Scripts
    subgraph "Build & Install"
        BuildScript["build.sh"]:::internal
        WinScript["install-win.ps1"]:::internal
        UnixScript["install"]:::internal
        Version["version.txt"]:::config
    end

    %% Main Flow
    User --> Main
    Main --> TUI
    Main --> Client
    TUI --> Client
    Client -.-> Config
    Client --> PR
    PR --> DS
    PR --> DDG
    PR --> GEM
    PR --> GROQ
    PR --> ISO
    PR --> KIM
    PR --> KOB
    PR --> OLL
    PR --> OPN
    PR --> PHI
    PR --> POL_T
    PR --> SKY
    Client --> IMGCORE
    IMGCORE --> ARTA
    IMGCORE --> POL_I

    DS --> E_OPENAI
    GEM --> E_GEMINI
    POL_I --> E_POLL_IMG
    ARTA --> E_POLL_IMG

    E_OPENAI --> DS
    E_GEMINI --> GEM
    E_POLL_IMG --> POL_I
    E_POLL_IMG --> ARTA

    DS --> Client
    GEM --> Client
    POL_T --> Client
    POL_I --> Client
    ARTA --> Client

    Client --> Stdout
    Client --> TUI

    %% Utility Dependencies
    Client --> Structs
    Client --> Utils
    Client --> Helper
    PR --> Structs
    IMGCORE --> Structs

    %% Styles
    classDef internal fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef external fill:#C8E6C9,stroke:#2E7D32,color:#000
    classDef config fill:#FFECB3,stroke:#FFA000,color:#000

    %% Click Events
    click Main "https://github.com/aandrew-me/tgpt/blob/main/main.go"
    click TUI "https://github.com/aandrew-me/tgpt/blob/main/src/bubbletea/bubbletea.go"
    click Client "https://github.com/aandrew-me/tgpt/blob/main/src/client/client.go"
    click PR "https://github.com/aandrew-me/tgpt/blob/main/src/providers/providers.go"
    click DS "https://github.com/aandrew-me/tgpt/blob/main/src/providers/deepseek/deepseek.go"
    click DDG "https://github.com/aandrew-me/tgpt/blob/main/src/providers/duckduckgo/duckduckgo.go"
    click GEM "https://github.com/aandrew-me/tgpt/blob/main/src/providers/gemini/gemini.go"
    click GROQ "https://github.com/aandrew-me/tgpt/blob/main/src/providers/groq/groq.go"
    click ISO "https://github.com/aandrew-me/tgpt/blob/main/src/providers/isou/isou.go"
    click KIM "https://github.com/aandrew-me/tgpt/blob/main/src/providers/kimi/kimi.go"
    click KOB "https://github.com/aandrew-me/tgpt/blob/main/src/providers/koboldai/koboldai.go"
    click OLL "https://github.com/aandrew-me/tgpt/blob/main/src/providers/ollama/ollama.go"
    click OPN "https://github.com/aandrew-me/tgpt/blob/main/src/providers/openai/openai.go"
    click PHI "https://github.com/aandrew-me/tgpt/blob/main/src/providers/phind/phind.go"
    click POL_T "https://github.com/aandrew-me/tgpt/blob/main/src/providers/pollinations/pollinations.go"
    click SKY "https://github.com/aandrew-me/tgpt/blob/main/src/providers/sky/sky.go"
    click IMGCORE "https://github.com/aandrew-me/tgpt/blob/main/src/imagegen/imagegen.go"
    click ARTA "https://github.com/aandrew-me/tgpt/blob/main/src/imagegen/arta/arta.go"
    click POL_I "https://github.com/aandrew-me/tgpt/blob/main/src/imagegen/pollinations/pollinations.go"
    click Structs "https://github.com/aandrew-me/tgpt/blob/main/src/structs/structs.go"
    click Utils "https://github.com/aandrew-me/tgpt/blob/main/src/utils/utils.go"
    click Helper "https://github.com/aandrew-me/tgpt/blob/main/src/helper/helper.go"
    click Config "https://github.com/aandrew-me/tgpt/blob/main/tgpt.json"
    click Version "https://github.com/aandrew-me/tgpt/blob/main/version.txt"
    click BuildScript "https://github.com/aandrew-me/tgpt/blob/main/build.sh"
    click WinScript "https://github.com/aandrew-me/tgpt/blob/main/install-win.ps1"
    click UnixScript "https://github.com/aandrew-me/tgpt/tree/main/install"
```
