# shellhub-io/shellhub architecture

> Architecture diagram of the GitHub repository shellhub-io/shellhub, 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/shellhub-io/shellhub
- Repository: https://github.com/shellhub-io/shellhub

## Overview

##### Main components
- Agent – Found in the “agent” directory (with Dockerfiles, Go code, and packaging scripts). This service runs locally on target devices and handles remote connections.
- API Server – In the “api” folder, it contains REST endpoints, business logic, service layers, and database interaction code (with extensive “mongo” store implementations). This is your central backend.
- Gateway – The “gateway” folder indicates a reverse proxy-like component that likely mediates SSH connections through a web interface, dealing with tasks like certificate handling and load balancing.
- SSH Service – The “ssh” directory suggests an SSH daemon/service that manages session initiation, authentication (via public-key mechanisms), and channel multiplexing.
- CLI – The “cli” folder is the command-line client used for administration; it interacts with the API to perform tasks such as user creation and device management.
- UI – “ui” hosts the web dashboard for administering the service, with an admin panel, client-side API calls, and various views.
- Supporting libraries and infrastructure – The “pkg” directory includes various packages (for caching, tunneling, logs, authentication, worker queues, etc.) which are used by the above services. There are also devscripts, tests, and additional configuration files that support CI/CD and deployment.

##### Out the relationships and interactions
- The UI and CLI are client-facing interfaces that send requests (HTTP/REST) to the API server.
- The API server, as the orchestration hub, leverages packages and service layers (such as authentication, logging, and firewall rules) and interacts with the database for state persistence.
- The API may also communicate with the agent service for tasks like initialization and management on remote devices.
- The Gateway and SSH service work in tandem to secure incoming SSH connections and to forward traffic appropriately. They implement design principles like public-key authentication, session recording, and firewall enforcement.

##### Architectural Patterns
- Although not strictly microservices (they share the same codebase and language), the separation into distinct directories (agent, api, gateway, ssh, cli, ui) reflects a modular architecture.
- There is a separation between control-plane (API server, UI, CLI) and data plane (agent, SSH endpoints, gateway).
- Usage of dependency injection and layered architecture in Go packages permits reusability and testability.

##### Relevant technologies
- Go (all main services written in Go), Docker (with multiple Dockerfiles and docker-compose configurations), and web front-end technologies (Vue.js for the admin UI appears indicated by the “ui” folder structure).
- MongoDB for data persistence, Redis (for caching) and integration with third‐party libraries for SSH (for session handling and public key authentication).

##### Final Recommendations
- Drill down into the API Server to show interactions with the Agent, SSH gateway, and database.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Interfaces"
        CLI["CLI Client"]:::client
        UI["Admin UI"]:::client
    end

    subgraph "Control Plane"
        API["API Server"]:::backend
        LIB["Supporting Libraries"]:::backend
    end

    subgraph "Data Plane"
        AGENT["Agent Service"]:::dataplane
        GATEWAY["Gateway"]:::dataplane
        SSH["SSH Service"]:::dataplane
    end

    subgraph "External Systems"
        MONGO["MongoDB"]:::external
        REDIS["Redis Cache"]:::external
        EX_SSH["External SSH Client"]:::external
    end

    %% Connections: Client Interfaces to Control Plane
    CLI -->|"HTTP/REST"| API
    UI  -->|"HTTP/REST"| API

    %% Control Plane interactions
    API -->|"uses"| LIB
    API -->|"manages"| AGENT
    API -->|"persists"| MONGO
    API -->|"caches"| REDIS

    %% External SSH flow into Data Plane
    EX_SSH -->|"SSHConnection"| GATEWAY
    GATEWAY -->|"forwards"| SSH

    %% Click Events
    click CLI "https://github.com/shellhub-io/shellhub/tree/master/cli"
    click UI "https://github.com/shellhub-io/shellhub/tree/master/ui"
    click API "https://github.com/shellhub-io/shellhub/tree/master/api"
    click LIB "https://github.com/shellhub-io/shellhub/tree/master/pkg"
    click AGENT "https://github.com/shellhub-io/shellhub/tree/master/agent"
    click GATEWAY "https://github.com/shellhub-io/shellhub/tree/master/gateway"
    click SSH "https://github.com/shellhub-io/shellhub/tree/master/ssh"

    %% Styles
    classDef client fill:#CCE5FF,stroke:#2E86C1,stroke-width:2px;
    classDef backend fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef dataplane fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef external fill:#FDEDEC,stroke:#CB4335,stroke-width:2px;
```
