# virtualcable/openuds architecture

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

- Interactive diagram: https://gitdiagram.com/virtualcable/openuds
- Repository: https://github.com/virtualcable/openuds

## Overview

##### Project type and purpose
- OpenUDS is a multi‐repo, full‐stack, microservice‐style connection broker for virtual desktops (VDI), app virtualization and desktop service consolidation.
- Top‐level submodules:
- actor – a background agent (“actor”) that polls the server and instantiates user sessions/transports
- client – CLI or library for issuing REST calls to the server
- guacamole-auth-uds – Apache Guacamole authentication plugin
- server – the main Django web/API application, containing REST handlers, core business logic, plugins, workers
- tunnel-server – a minimal tunnel‐proxy service

##### File structure
- server/src/server – Django project (manage.py, settings.py.sample, wsgi/asgi, urls.py)
- server/src/uds – the main Django app, with subpackages:
- REST – HTTP/JSON API dispatchers & handlers (business → serializers → models → managers)
- admin, web/views/templates/static – presentation layer (Django templates + modern SPA assets)
- auths, mfas, notifiers – plugin points for authentication, multi-factor, notification backends
- core – central abstractions (auth factory, jobs scheduler, messaging, managers, util)
- services – connectors to external virtualization backends (OpenStack, Xen, Proxmox, OVirt, etc.)
- osmanagers – OS‐level user provisioning managers (Linux, Windows domain, test stub)
- transports – code and per‐OS scripts to launch RDP, VNC, SSH, X2Go sessions
- workers – internal task runners (stats collection, cleanup, scheduler housekeepers)
- Configuration files (.pylintrc, mypy.ini, pytest.ini) and CI workflows (.github/workflows)

##### README
- Confirms it is an open‐source, Python 3.10+ Django project, split across multiple repositories.
- Master is under development; stable branches use v4.0.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Points (Green)
    Browser["Web Browser"]:::entry
    CLI["CLI Tools"]:::entry
    UDSClient["UDS Desktop Clients"]:::entry
    ActorMS["Actor Service"]:::entry
    TunnelMS["Tunnel Server"]:::entry
    GuacPlugin["Guacamole Auth Plugin"]:::entry

    %% Django Server Boundary
    subgraph "Django Server"
        direction TB
        %% Presentation Layer
        subgraph "Presentation Layer"
            direction TB
            Templates["Templates"]:::blue
            StaticAssets["Static Assets"]:::blue
            WebSPA["SPA Web Assets"]:::blue
        end

        %% API Layer
        REST["Django REST API Layer"]:::blue

        %% Business Logic & Plugins
        subgraph "Business Logic"
            direction TB
            Core["Core Business Logic"]:::blue
            subgraph "Plugin Framework"
                direction TB
                Auths["Auth Plugins"]:::blue
                MFAs["MFA Plugins"]:::blue
                Notifiers["Notifier Plugins"]:::blue
                Services["Virtualization Connectors"]:::blue
                OSManagers["OS Provisioning Managers"]:::blue
                Transports["Transport Launchers"]:::blue
            end
        end

        %% Workers
        Workers["Background Workers"]:::orange

        %% Data Layer
        subgraph "Data & Routing"
            direction TB
            Models["Data Models & ORM"]:::blue
            Commands["Management Commands"]:::blue
            Routing["URL Routing & Dispatchers"]:::blue
        end
    end

    %% External Systems
    DB["Database (PostgreSQL/MySQL)"]:::external
    Broker["Message Broker"]:::orange
    ExtProviders["Virtualization Backends"]:::external

    %% Connections
    Browser -->|"HTTPS UI"| Templates
    Browser -->|"HTTPS UI"| StaticAssets
    Browser -->|"HTTPS UI"| WebSPA
    CLI -->|"REST API Calls"| REST
    UDSClient -->|"REST & Tunnel"| REST
    ActorMS -->|"REST Polling"| REST
    ActorMS -->|"Spawn Transports"| Transports
    REST -->|"ORM Queries"| Models
    REST -->|"Publish Jobs"| Broker
    Workers -->|"Consume Jobs"| Broker
    REST -->|"Load Plugins"| Auths
    REST -->|"Load Plugins"| MFAs
    REST -->|"Load Plugins"| Notifiers
    REST -->|"Invoke Services"| Services
    REST -->|"Invoke OS Managers"| OSManagers
    REST -->|"Invoke Transports"| Transports
    REST -->|"Provider API Calls"| ExtProviders
    GuacPlugin -->|"REST Calls"| REST
    TunnelMS -->|"Proxy Tunnels"| UDSClient

    %% Click Events
    click ActorMS "https://github.com/virtualcable/openuds/tree/master/actor/"
    click CLI "https://github.com/virtualcable/openuds/tree/master/client/"
    click GuacPlugin "https://github.com/virtualcable/openuds/tree/master/guacamole-auth-uds/"
    click TunnelMS "https://github.com/virtualcable/openuds/tree/master/tunnel-server/"
    click Templates "https://github.com/virtualcable/openuds/tree/master/server/src/uds/templates/"
    click StaticAssets "https://github.com/virtualcable/openuds/tree/master/server/src/uds/static/"
    click WebSPA "https://github.com/virtualcable/openuds/tree/master/server/src/uds/web/"
    click REST "https://github.com/virtualcable/openuds/tree/master/server/src/uds/REST/"
    click Auths "https://github.com/virtualcable/openuds/tree/master/server/src/uds/auths/"
    click MFAs "https://github.com/virtualcable/openuds/tree/master/server/src/uds/mfas/"
    click Notifiers "https://github.com/virtualcable/openuds/tree/master/server/src/uds/notifiers/"
    click Core "https://github.com/virtualcable/openuds/tree/master/server/src/uds/core/"
    click Services "https://github.com/virtualcable/openuds/tree/master/server/src/uds/services/"
    click OSManagers "https://github.com/virtualcable/openuds/tree/master/server/src/uds/osmanagers/"
    click Transports "https://github.com/virtualcable/openuds/tree/master/server/src/uds/transports/"
    click Workers "https://github.com/virtualcable/openuds/tree/master/server/src/uds/workers/"
    click Models "https://github.com/virtualcable/openuds/tree/master/server/src/uds/models/"
    click Commands "https://github.com/virtualcable/openuds/tree/master/server/src/uds/management/commands/"
    click Routing "https://github.com/virtualcable/openuds/blob/master/server/src/uds/urls.py"
    click DB "https://github.com/virtualcable/openuds/tree/master/server/src/server/"
    click Broker "https://github.com/virtualcable/openuds/tree/master/server/src/server/"

    %% Styles
    classDef entry fill:#b2f5bf,stroke:#2f855a,color:#22543d;
    classDef blue fill:#bee3f8,stroke:#2b6cb0,color:#2c5282;
    classDef orange fill:#fbd38d,stroke:#dd6b20,color:#7b341e;
    classDef external fill:#e2e8f0,stroke:#718096,color:#1a202c;
```
