# manics/jupyterhub-virtualdesktopspawner architecture

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

- Interactive diagram: https://gitdiagram.com/manics/jupyterhub-virtualdesktopspawner
- Repository: https://github.com/manics/jupyterhub-virtualdesktopspawner

## Overview

Key Components to Include:

##### Core Infrastructure Layer
- Kubernetes Cluster (primary hosting platform)
- AWS EC2 (for Windows VMs)
- Networking components (VPC, Subnets)

##### Main Application Components
- JupyterHub (central orchestrator)
- Virtual Desktop Spawner Service
- Linux Desktop Spawner (Container-based)
- Windows Desktop Spawner (EC2-based)
- Apache Guacamole (remote desktop access service)

##### Authentication & Authorization
- AWS IAM/IRSA integration
- Kubernetes Service Accounts
- SSM (AWS Systems Manager for Windows instances)

##### Component Relationships
- User → Apache Guacamole (browser access)
- JupyterHub → Virtual Desktop Spawner
- Virtual Desktop Spawner → Two paths:
a. Linux path: Direct to Kubernetes Containers
b. Windows path: To AWS EC2 via AWS API

##### Specific Implementation Details
- Separation between the two spawner types (KubeEC2Spawner and container-based)
- IAM role and policy connections
- VPC/Subnet configuration for EC2 instances
- Guacamole connection broker

##### Additional Elements
- Version compatibility notes
- Development status (as it's under development)
- Configuration file references (z2jh-linuxdesktops.yaml, z2jh-windowsdesktops.yaml)

- The hybrid nature of the solution (container + VM based)
- Security boundaries and authentication flows
- Clear separation of Linux and Windows paths
- Integration points with cloud services

Remember to:
- Keep the main flow clear and easy to follow
- Necessary security components
- Scaling capabilities
- Failure recovery paths
- Development/beta components

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Access Layer"
        User((End User))
        Browser[Web Browser]
    end

    subgraph "Control Plane Layer"
        JHub[JupyterHub]
        GuacService[Apache Guacamole]
        VDSpawner[Virtual Desktop Spawner]:::spawner
        
        subgraph "Spawner Types"
            LinuxSpawner[Linux Desktop Spawner]:::linux
            WinSpawner[Windows Desktop Spawner]:::windows
        end
    end

    subgraph "Infrastructure Layer"
        subgraph "Kubernetes Resources"
            K8sNS[Kubernetes Namespace]
            LinuxPods[Linux Desktop Pods]:::linux
        end

        subgraph "AWS Resources"
            EC2[AWS EC2 Instances]:::aws
            SSM[Systems Manager]:::aws
            VPC[VPC/Subnets]:::aws
        end
    end

    subgraph "Authentication Layer"
        IAM[AWS IAM]:::auth
        IRSA[IAM Roles for Service Accounts]:::auth
        K8SA[Kubernetes Service Accounts]:::auth
    end

    %% Connections
    User --> Browser
    Browser --> GuacService
    GuacService --> JHub
    JHub --> VDSpawner
    VDSpawner --> LinuxSpawner
    VDSpawner --> WinSpawner
    LinuxSpawner --> LinuxPods
    WinSpawner --> EC2
    EC2 --> SSM
    EC2 --> VPC
    
    %% Authentication Flows
    VDSpawner --> IRSA
    IRSA --> IAM
    IRSA --> K8SA
    
    %% Styling
    classDef aws fill:#90EE90
    classDef auth fill:#DDA0DD
    classDef linux fill:#ADD8E6
    classDef windows fill:#FFB6C1
    classDef spawner fill:#F0E68C

    %% Click Events
    click VDSpawner "https://github.com/manics/jupyterhub-virtualdesktopspawner/blob/main/virtualdesktopspawner/kubeec2spawner.py"
    click EC2 "https://github.com/manics/jupyterhub-virtualdesktopspawner/blob/main/virtualdesktopspawner/awsec2.py"
    click IAM "https://github.com/manics/jupyterhub-virtualdesktopspawner/blob/main/aws-iam/aws-ec2ssm-iam-policy.json"
    click LinuxSpawner "https://github.com/manics/jupyterhub-virtualdesktopspawner/blob/main/configs/z2jh-linuxdesktops.yaml"
    click WinSpawner "https://github.com/manics/jupyterhub-virtualdesktopspawner/blob/main/configs/z2jh-windowsdesktops.yaml"

    %% Legend
    subgraph Legend
        L1[AWS Services]:::aws
        L2[Authentication Components]:::auth
        L3[Linux Components]:::linux
        L4[Windows Components]:::windows
        L5[Spawner Services]:::spawner
    end
```
