# hexsecteam/hexsecgpt architecture

> Architecture diagram of the GitHub repository hexsecteam/hexsecgpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hexsecteam/hexsecgpt
- Repository: https://github.com/hexsecteam/hexsecgpt

## Overview

HexSecGPT is a Python CLI wrapper around third-party language-model APIs, not the repository’s private fine-tuned model. Its main workflow is API-key setup and verification, then interactive chat with session controls and streamed Markdown display. The README also documents switching between OpenRouter and DeepSeek, plus a separate script for discovering free OpenRouter models. Some implementation sections were not excerpted, so links for those documented capabilities rely on the README rather than unsampled code.

Main entry points: [`HexSecGPT.py`](https://github.com/hexsecteam/hexsecgpt/blob/main/HexSecGPT.py) (App orchestration), [`SeeOpenRouterFreeModels.py`](https://github.com/hexsecteam/hexsecgpt/blob/main/SeeOpenRouterFreeModels.py) (Free-model finder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI experience"]
  node_app["App orchestration<br/>[HexSecGPT.py]"]
  node_ui["Terminal UI<br/>[HexSecGPT.py]"]
  node_credentials["API key setup<br/>[HexSecGPT.py]"]
end

subgraph group_runtime["Chat runtime"]
  node_brain["Chat brain<br/>[HexSecGPT.py]"]
  node_history["Conversation history<br/>[HexSecGPT.py]"]
  node_provider{{"LLM API provider"}}
end

subgraph group_discovery["Model discovery"]
  node_openrouter{{"OpenRouter models"}}
  node_modelfinder["Free-model finder"]
end

node_user(("CLI user"))

node_user -->|"starts and uses"| node_app
node_app -->|"prompts and displays"| node_ui
node_app -->|"configures key"| node_credentials
node_app -->|"initializes"| node_brain
node_app -->|"verifies credentials"| node_brain
node_app -->|"collects chat input"| node_ui
node_app -->|"resets session"| node_brain
node_brain -->|"requests completions"| node_provider
node_brain -->|"maintains messages"| node_history
node_app -->|"selects OpenRouter or DeepSeek"| node_provider
node_modelfinder -->|"fetches model list"| node_openrouter
node_modelfinder -->|"prints free models"| node_user
node_user -->|"runs discovery"| node_modelfinder
node_user -->|"updates model choice"| node_app

click node_app "https://github.com/hexsecteam/hexsecgpt/blob/main/HexSecGPT.py"
click node_ui "https://github.com/hexsecteam/hexsecgpt/blob/main/HexSecGPT.py"
click node_credentials "https://github.com/hexsecteam/hexsecgpt/blob/main/HexSecGPT.py"
click node_brain "https://github.com/hexsecteam/hexsecgpt/blob/main/HexSecGPT.py"
click node_history "https://github.com/hexsecteam/hexsecgpt/blob/main/HexSecGPT.py"
click node_modelfinder "https://github.com/hexsecteam/hexsecgpt/blob/main/SeeOpenRouterFreeModels.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_ui,node_credentials,node_user toneBlue
class node_brain,node_history,node_provider toneAmber
class node_openrouter,node_modelfinder toneMint
```

## Components

### CLI experience

- [App orchestration](https://github.com/hexsecteam/hexsecgpt/blob/main/HexSecGPT.py): `HexSecGPT.py`
- [Terminal UI](https://github.com/hexsecteam/hexsecgpt/blob/main/HexSecGPT.py): `HexSecGPT.py`
- [API key setup](https://github.com/hexsecteam/hexsecgpt/blob/main/HexSecGPT.py): `HexSecGPT.py`

### Chat runtime

- [Chat brain](https://github.com/hexsecteam/hexsecgpt/blob/main/HexSecGPT.py): `HexSecGPT.py`
- [Conversation history](https://github.com/hexsecteam/hexsecgpt/blob/main/HexSecGPT.py): `HexSecGPT.py`
- **LLM API provider**

### Model discovery

- **OpenRouter models**
- [Free-model finder](https://github.com/hexsecteam/hexsecgpt/blob/main/SeeOpenRouterFreeModels.py): `SeeOpenRouterFreeModels.py`

### Other components

- **CLI user**

## Connections

- CLI user → App orchestration: starts and uses (evidence: `README.md`)
- App orchestration → Terminal UI: prompts and displays (evidence: `HexSecGPT.py`)
- App orchestration → API key setup: configures key (evidence: `HexSecGPT.py`)
- App orchestration → Chat brain: initializes (evidence: `HexSecGPT.py`)
- App orchestration → Chat brain: verifies credentials (evidence: `HexSecGPT.py`)
- App orchestration → Terminal UI: collects chat input (evidence: `HexSecGPT.py`)
- App orchestration → Chat brain: resets session (evidence: `HexSecGPT.py`)
- Chat brain → LLM API provider: requests completions (evidence: `HexSecGPT.py`)
- Chat brain → Conversation history: maintains messages (evidence: `HexSecGPT.py`)
- App orchestration → LLM API provider: selects OpenRouter or DeepSeek (evidence: `README.md`)
- Free-model finder → OpenRouter models: fetches model list (evidence: `SeeOpenRouterFreeModels.py`)
- Free-model finder → CLI user: prints free models (evidence: `SeeOpenRouterFreeModels.py`)
- CLI user → Free-model finder: runs discovery (evidence: `README.md`)
- CLI user → App orchestration: updates model choice (evidence: `README.md`)
