# upc/ravada architecture

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

- Interactive diagram: https://gitdiagram.com/upc/ravada
- Repository: https://github.com/upc/ravada

## Overview

##### Project type and purpose
- This is ravada, an open-source Remote Virtual Desktops Manager (a full-stack web application plus background daemon) for provisioning and accessing QEMU/KVM VMs via a browser/SPICE client.
- The README confirms its goal: web UI for VM life-cycle management, snapshot/clone, LDAP/SQL auth, remote console (SPICE).

##### File structure
- Top-level “dockerfy” holds two containers: back (rvd_back daemon) and front (web server).
- “lib/Ravada” contains Perl modules implementing the core API, domain drivers (KVM, LXC), authentication, booking, volume, networking, WebSocket.
- “script/rvd_back” and “script/rvd_front” are entrypoints for the backend daemon and frontend web server.
- “public/” holds static assets (CSS, JS, fonts, images) and AngularJS modules (“public/js/booking”).
- “templates/” and “public/templates/” store server-side (Mojolicious) and Angular/HTML templates.
- “sql/” holds schemas for MySQL and SQLite plus upgrade scripts.
- “etc/” holds configuration files (ravada.conf, systemd units), XML definitions for VM images/templates.

##### README for additional insights
- Backend written in Perl, uses Mojolicious (the presence of .ep templates and WebSocket modules)
- Supports LDAP, SQL auth, KVM hypervisor driver by default, plug-in architecture for other hypervisors.
- Typical deployment uses a DB (MySQL/PostgreSQL/SQLite), an HTTP front, and a daemon that talks to libvirt.

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "UI Layer"
    script_rf["script/rvd_front"]:::frontend
    lib_front_pm["lib/Ravada/Front.pm"]:::frontend
    front_domain["lib/Ravada/Front/Domain/"]:::frontend
    public_css["public/css/"]:::frontend
    public_js["public/js/"]:::frontend
    public_templates["public/templates/"]:::frontend
    templates["templates/"]:::frontend
    ng_templates["templates/ng-templates/"]:::frontend
    docker_front_docker["dockerfy/dockers/front/Dockerfile"]:::frontend
    docker_front_conf["dockerfy/dockers/front/ravada.conf"]:::frontend
    rvd_front_service["rvd_front Service"]:::frontend
    script_rf --> rvd_front_service
    lib_front_pm --> rvd_front_service
    front_domain --> rvd_front_service
    public_css --> rvd_front_service
    public_js --> rvd_front_service
    public_templates --> rvd_front_service
    templates --> rvd_front_service
    ng_templates --> rvd_front_service
    docker_front_docker --> rvd_front_service
    docker_front_conf --> rvd_front_service
  end

  subgraph "Orchestration Layer"
    script_rb["script/rvd_back"]:::backend
    lib_ravada_pm["lib/Ravada.pm"]:::backend
    core_api["lib/Ravada/"]:::backend
    driver_pm["lib/Ravada/Domain/Driver.pm"]:::backend
    kvm_driver["lib/Ravada/Domain/KVM.pm"]:::backend
    lxc_driver["lib/Ravada/Domain/LXC.pm"]:::backend
    void_driver["lib/Ravada/Domain/Void.pm"]:::backend
    websocket_pm["lib/Ravada/WebSocket.pm"]:::backend
    docker_back_docker["dockerfy/dockers/back/Dockerfile"]:::backend
    docker_back_conf["dockerfy/dockers/back/ravada.conf"]:::backend
    ldap_module["lib/Ravada/Auth/LDAP.pm"]:::backend
    sql_module["lib/Ravada/Auth/SQL.pm"]:::backend
    rvd_back_service["rvd_back Service"]:::backend
    script_rb --> rvd_back_service
    lib_ravada_pm --> rvd_back_service
    core_api --> rvd_back_service
    driver_pm --> rvd_back_service
    kvm_driver --> rvd_back_service
    lxc_driver --> rvd_back_service
    void_driver --> rvd_back_service
    websocket_pm --> rvd_back_service
    docker_back_docker --> rvd_back_service
    docker_back_conf --> rvd_back_service
    ldap_module --> rvd_back_service
    sql_module --> rvd_back_service
  end

  subgraph "Data Layer"
    sql_mysql["sql/mysql/"]:::data
    sql_sqlite["sql/sqlite/"]:::data
    sql_data["sql/data/"]:::data
    sql_upgrades["sql/upgrades/"]:::data
  end

  subgraph "Hypervisor Layer"
    vm_kvm["lib/Ravada/VM/KVM.pm"]:::hypervisor
    net_kvm["lib/Ravada/NetInterface/KVM.pm"]:::hypervisor
    default_xml["dockerfy/dockers/back/default.xml"]:::hypervisor
  end

  subgraph "Configuration"
    etc_ravada_conf["etc/ravada.conf"]:::config
    etc_rvd_front_example["etc/rvd_front.conf.example"]:::config
    etc_rvd_front_service["etc/systemd/rvd_front.service"]:::config
    etc_rvd_back_service["etc/systemd/rvd_back.service"]:::config
    env_file["dockerfy/.env"]:::config
    compose_file["dockerfy/docker-compose.yml"]:::config
  end

  subgraph "External Services"
    user_browser["User Browser"]:::external
    ldap_server["LDAP Server"]:::external
    spice_client["SPICE Client"]:::external
  end

  user_browser -->|"HTTP(S) requests"| rvd_front_service
  rvd_front_service -->|"DB read/write"| sql_mysql
  rvd_front_service -->|"DB read/write"| sql_sqlite
  rvd_back_service -->|"DB read/write"| sql_mysql
  rvd_back_service -->|"DB read/write"| sql_sqlite
  rvd_front_service -->|"WebSocket events"| rvd_back_service
  rvd_front_service -->|"auth"| ldap_server
  rvd_back_service -->|"auth"| ldap_server
  rvd_back_service -->|"libvirt API calls"| vm_kvm
  vm_kvm --> net_kvm
  vm_kvm -->|"uses VM XML"| default_xml
  vm_kvm -->|"SPICE streaming"| spice_client

  click script_rf "https://github.com/upc/ravada/tree/main/script/rvd_front"
  click lib_front_pm "https://github.com/upc/ravada/blob/main/lib/Ravada/Front.pm"
  click front_domain "https://github.com/upc/ravada/tree/main/lib/Ravada/Front/Domain/"
  click public_css "https://github.com/upc/ravada/tree/main/public/css/"
  click public_js "https://github.com/upc/ravada/tree/main/public/js/"
  click public_templates "https://github.com/upc/ravada/tree/main/public/templates/"
  click templates "https://github.com/upc/ravada/tree/main/templates/"
  click ng_templates "https://github.com/upc/ravada/tree/main/templates/ng-templates/"
  click docker_front_docker "https://github.com/upc/ravada/tree/main/dockerfy/dockers/front/Dockerfile"
  click docker_front_conf "https://github.com/upc/ravada/blob/main/dockerfy/dockers/front/ravada.conf"
  click script_rb "https://github.com/upc/ravada/tree/main/script/rvd_back"
  click lib_ravada_pm "https://github.com/upc/ravada/blob/main/lib/Ravada.pm"
  click core_api "https://github.com/upc/ravada/tree/main/lib/Ravada/"
  click driver_pm "https://github.com/upc/ravada/blob/main/lib/Ravada/Domain/Driver.pm"
  click kvm_driver "https://github.com/upc/ravada/blob/main/lib/Ravada/Domain/KVM.pm"
  click lxc_driver "https://github.com/upc/ravada/blob/main/lib/Ravada/Domain/LXC.pm"
  click void_driver "https://github.com/upc/ravada/blob/main/lib/Ravada/Domain/Void.pm"
  click websocket_pm "https://github.com/upc/ravada/blob/main/lib/Ravada/WebSocket.pm"
  click docker_back_docker "https://github.com/upc/ravada/tree/main/dockerfy/dockers/back/Dockerfile"
  click docker_back_conf "https://github.com/upc/ravada/blob/main/dockerfy/dockers/back/ravada.conf"
  click ldap_module "https://github.com/upc/ravada/blob/main/lib/Ravada/Auth/LDAP.pm"
  click sql_module "https://github.com/upc/ravada/blob/main/lib/Ravada/Auth/SQL.pm"
  click sql_mysql "https://github.com/upc/ravada/tree/main/sql/mysql/"
  click sql_sqlite "https://github.com/upc/ravada/tree/main/sql/sqlite/"
  click sql_data "https://github.com/upc/ravada/tree/main/sql/data/"
  click sql_upgrades "https://github.com/upc/ravada/tree/main/sql/upgrades/"
  click vm_kvm "https://github.com/upc/ravada/blob/main/lib/Ravada/VM/KVM.pm"
  click net_kvm "https://github.com/upc/ravada/blob/main/lib/Ravada/NetInterface/KVM.pm"
  click default_xml "https://github.com/upc/ravada/blob/main/dockerfy/dockers/back/default.xml"
  click etc_ravada_conf "https://github.com/upc/ravada/blob/main/etc/ravada.conf"
  click etc_rvd_front_example "https://github.com/upc/ravada/blob/main/etc/rvd_front.conf.example"
  click etc_rvd_front_service "https://github.com/upc/ravada/blob/main/etc/systemd/rvd_front.service"
  click etc_rvd_back_service "https://github.com/upc/ravada/blob/main/etc/systemd/rvd_back.service"
  click env_file "https://github.com/upc/ravada/blob/main/dockerfy/.env"
  click compose_file "https://github.com/upc/ravada/blob/main/dockerfy/docker-compose.yml"

  classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
  classDef data fill:#FFA500,stroke:#333,stroke-width:1px
  classDef hypervisor fill:#DDA0DD,stroke:#333,stroke-width:1px
  classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
  classDef config fill:#F0E68C,stroke:#333,stroke-width:1px
```
