# shubhamoy/socktunnel architecture

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

- Interactive diagram: https://gitdiagram.com/shubhamoy/socktunnel
- Repository: https://github.com/shubhamoy/socktunnel

## Overview

##### Project Type & Purpose
- Type: A cross‑platform desktop application (Qt/C++17)
- Purpose: Provide a GUI wrapper around `ssh -D` for SOCKS5 tunneling, auto‑detect SSH hosts, toggle system proxy, and show public IP before/after tunnel.

##### File Structure
- src/app: Entry point and application‑level orchestration
– SocksProxyApp (C++ class) initializes core modules and UI
– main.cpp boots the Qt application
- src/core: Business logic modules
– SshConfigParser: reads `~/.ssh/config`
– SshProxyManager: spawns/manages `ssh -D` subprocess (via QProcess)
– PublicIPChecker: fetches public IP (via QtNetwork)
– SystemProxyConfigurer: toggles OS proxy (macOS via networksetup, Linux via DBus)
– Logger: centralized logging
- src/ui: Presentation layer
– SocksProxyUI: main widgets & dialogs
– CenterAlignDelegate: custom item delegate for host list

##### Key Architecture Insights from README
- Qt6 Widgets, Network, SvgWidgets, DBus
- CMake for build configuration
- MVC‑like separation: UI ↔ Core ↔ External OS/Network

a. Main Components
1. UI Layer (SocksProxyUI, Delegates)
2. Application Controller (SocksProxyApp)
3. Core Module Suite
– SshConfigParser
– SshProxyManager
– PublicIPChecker
– SystemProxyConfigurer
– Logger
4. External Systems
– SSH CLI (`ssh -D`)
– OS Proxy Settings (system services or DBus)
– Internet (for PublicIPChecker)
b. Interactions & Data Flow
1. User clicks “Connect” in UI → emits signal to SocksProxyApp
2. SocksProxyApp calls SshConfigParser to load hosts → UI dropdown populates
3. On “Start Tunnel,” SocksProxyApp invokes SshProxyManager → launches SSH process
4. Once SSH is up, SystemProxyConfigurer toggles OS proxy to localhost:port
5. PublicIPChecker polls “before” and “after” IPs → updates UI
6. Logger records actions/errors throughout all modules
7. On “Stop Tunnel,” reverse steps; teardown SSH, restore proxy
c. Architectural Patterns & Principles
- Modular separation: each core concern in its own class
- Signal/slot for loose coupling between UI and core
- Single Responsibility: parser, manager, configurer, checker, logger
- Resource bundling via Qt’s QRC system
d. Relevant Technologies
- Qt6 (Widgets, Network, DBus, SvgWidgets)
- QProcess (for SSH)
- QtNetworkAccessManager (for IP checks)
- CMake

##### Detail Without Overthinking
- How the SSH subprocess lives outside the main Qt process
- Logger is represented as a cross‑cutting service

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer"
        direction TB
        SocksProxyUI["SocksProxyUI"]:::ui
        CenterAlignDelegate["CenterAlignDelegate"]:::ui
    end

    subgraph "Controller"
        direction TB
        SocksProxyApp["SocksProxyApp"]:::controller
    end

    subgraph "Core Modules"
        direction TB
        SshConfigParser["SshConfigParser"]:::core
        SshProxyManager["SshProxyManager"]:::core
        PublicIPChecker["PublicIPChecker"]:::core
        SystemProxyConfigurer["SystemProxyConfigurer"]:::core
        Logger["Logger"]:::core
    end

    subgraph "External Systems"
        direction TB
        SSHProcess["SSH CLI\n(ssh -D)"]:::external
        OSProxySettings["OS Proxy Settings"]:::external
        Internet["Internet\n(Public IP)"]:::external
    end

    SocksProxyUI -->|"signal: connectClicked"| SocksProxyApp
    SocksProxyApp -->|"load hosts"| SshConfigParser
    SshConfigParser -->|"hosts list"| SocksProxyUI

    SocksProxyApp -->|"start tunnel"| SshProxyManager
    SshProxyManager -->|"launch SSH"| SSHProcess

    SocksProxyApp -->|"configure proxy"| SystemProxyConfigurer
    SystemProxyConfigurer -->|"toggle proxy"| OSProxySettings

    SocksProxyApp -->|"check IP"| PublicIPChecker
    PublicIPChecker -->|"request IP"| Internet
    Internet -->|"return IP"| PublicIPChecker
    PublicIPChecker -->|"update UI"| SocksProxyUI

    SocksProxyApp -->|"stop tunnel"| SshProxyManager
    SshProxyManager -->|"terminate process"| SSHProcess
    SocksProxyApp -->|"restore proxy"| SystemProxyConfigurer

    SocksProxyApp -->|"log events"| Logger
    SshConfigParser -->|"log events"| Logger
    SshProxyManager -->|"log events"| Logger
    PublicIPChecker -->|"log events"| Logger
    SystemProxyConfigurer -->|"log events"| Logger

    click SocksProxyUI "https://github.com/shubhamoy/socktunnel/blob/main/src/ui/SocksProxyUI.h"
    click CenterAlignDelegate "https://github.com/shubhamoy/socktunnel/blob/main/src/ui/CenterAlignDelegate.h"
    click SocksProxyApp "https://github.com/shubhamoy/socktunnel/blob/main/src/app/SocksProxyApp.h"
    click SshConfigParser "https://github.com/shubhamoy/socktunnel/blob/main/src/core/SshConfigParser.h"
    click SshProxyManager "https://github.com/shubhamoy/socktunnel/blob/main/src/core/SshProxyManager.h"
    click PublicIPChecker "https://github.com/shubhamoy/socktunnel/blob/main/src/core/PublicIPChecker.h"
    click SystemProxyConfigurer "https://github.com/shubhamoy/socktunnel/blob/main/src/core/SystemProxyConfigurer.h"
    click Logger "https://github.com/shubhamoy/socktunnel/blob/main/src/core/Logger.h"

    classDef ui fill:#ADD8E6,stroke:#000
    classDef controller fill:#87CEFA,stroke:#000
    classDef core fill:#98FB98,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
```
