# parallels/prl-devops-service architecture

> Architecture diagram of the GitHub repository parallels/prl-devops-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parallels/prl-devops-service
- Repository: https://github.com/parallels/prl-devops-service

## Overview

Parallels Desktop DevOps Service exposes VM management and status operations, with broader repository capabilities for catalog distribution, host orchestration, and reverse proxying. The principal workflow is a client request entering the REST API, passing authorization, and reaching a controller; VM operations are provided by the Parallels integration, while catalog-manager operations can persist manager records and initiate catalog jobs. The graph also shows distinct catalog, orchestration, and proxy branches visible in the tree. Wiring beyond the sampled excerpts is limited to clear module responsibilities; uncertain calls are omitted.

Main entry points: [`src/data/main.go`](https://github.com/parallels/prl-devops-service/blob/main/src/data/main.go) (Data access), [`src/controllers/main.go`](https://github.com/parallels/prl-devops-service/blob/main/src/controllers/main.go) (API controllers), [`src/restapi/controllers.go`](https://github.com/parallels/prl-devops-service/blob/main/src/restapi/controllers.go) (REST API), [`src/controllers/catalog_managers.go`](https://github.com/parallels/prl-devops-service/blob/main/src/controllers/catalog_managers.go) (Manager controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_rest["REST API<br/>[controllers.go]"]
  node_auth["Authorization middleware"]
  node_controllers["API controllers<br/>[main.go]"]
end

subgraph group_vm["VM management"]
  node_vmctrl["VM controller<br/>[machines.go]"]
  node_pd["Parallels service<br/>[main.go]"]
end

subgraph group_catalog["Catalog distribution"]
  node_catalogctrl["Catalog controllers<br/>[catalog.go]"]
  node_mgrctrl["Manager controllers"]
  node_catalogsvc["Catalog service<br/>[main.go]"]
  node_storage["Storage providers<br/>[main.go]"]
  node_cache["Catalog cache<br/>[main.go]"]
end

subgraph group_orchestration["Host orchestration"]
  node_orchestrator["Orchestrator operations<br/>[main.go]"]
  node_ws["Host WebSocket manager"]
end

subgraph group_runtime["State and integrations"]
  node_jobs["Job tracking<br/>[main.go]"]
  node_proxy["Reverse proxy<br/>[main.go]"]
  node_data["Data access<br/>[main.go]"]
  node_database[("JSON database<br/>[main.go]")]
  node_sql[("SQL service<br/>[service.go]")]
  node_event["Event emitter<br/>[main.go]"]
end

node_client(("API client"))
node_externalhost(("Managed host"))

node_client -->|"sends request"| node_rest
node_rest -->|"authorizes"| node_auth
node_rest -->|"dispatches"| node_controllers
node_controllers -->|"routes VM requests"| node_vmctrl
node_vmctrl -->|"manages VMs"| node_pd
node_controllers -->|"routes catalog requests"| node_catalogctrl
node_controllers -->|"routes manager requests"| node_mgrctrl
node_mgrctrl -->|"reads and writes"| node_data
node_mgrctrl -->|"creates catalog job"| node_jobs
node_catalogctrl -->|"catalog operations"| node_catalogsvc
node_catalogsvc -->|"uses provider"| node_storage
node_catalogsvc -->|"uses cache"| node_cache
node_orchestrator -->|"loads host state"| node_data
node_orchestrator -->|"manages host connections"| node_ws
node_ws -->|"connects"| node_externalhost
node_ws -->|"updates connection status"| node_data
node_proxy -->|"resolves VM targets"| node_pd
node_data -->|"accesses JSON store"| node_database
node_data -.->|"uses SQL service"| node_sql
node_pd -->|"broadcasts VM updates"| node_event

click node_rest "https://github.com/parallels/prl-devops-service/blob/main/src/restapi/controllers.go"
click node_auth "https://github.com/parallels/prl-devops-service/blob/main/src/restapi/token_authorization_middleware.go"
click node_controllers "https://github.com/parallels/prl-devops-service/blob/main/src/controllers/main.go"
click node_vmctrl "https://github.com/parallels/prl-devops-service/blob/main/src/controllers/machines.go"
click node_pd "https://github.com/parallels/prl-devops-service/blob/main/src/serviceprovider/parallelsdesktop/main.go"
click node_catalogctrl "https://github.com/parallels/prl-devops-service/blob/main/src/controllers/catalog.go"
click node_mgrctrl "https://github.com/parallels/prl-devops-service/blob/main/src/controllers/catalog_managers.go"
click node_catalogsvc "https://github.com/parallels/prl-devops-service/blob/main/src/catalog/main.go"
click node_storage "https://github.com/parallels/prl-devops-service/blob/main/src/catalog/providers/local/main.go"
click node_cache "https://github.com/parallels/prl-devops-service/blob/main/src/catalog/cacheservice/main.go"
click node_jobs "https://github.com/parallels/prl-devops-service/blob/main/src/jobs/main.go"
click node_orchestrator "https://github.com/parallels/prl-devops-service/blob/main/src/orchestrator/main.go"
click node_ws "https://github.com/parallels/prl-devops-service/blob/main/src/orchestrator/host_websocket_manager.go"
click node_proxy "https://github.com/parallels/prl-devops-service/blob/main/src/reverse_proxy/main.go"
click node_data "https://github.com/parallels/prl-devops-service/blob/main/src/data/main.go"
click node_database "https://github.com/parallels/prl-devops-service/blob/main/src/data/main.go"
click node_sql "https://github.com/parallels/prl-devops-service/blob/main/src/sql/service.go"
click node_event "https://github.com/parallels/prl-devops-service/blob/main/src/serviceprovider/eventEmitter/main.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rest,node_auth,node_controllers,node_client toneBlue
class node_vmctrl,node_pd toneAmber
class node_catalogctrl,node_mgrctrl,node_catalogsvc,node_storage,node_cache toneMint
class node_orchestrator,node_ws toneRose
class node_jobs,node_proxy,node_data,node_database,node_sql,node_event,node_externalhost toneIndigo
```

## Components

### API and access

- [REST API](https://github.com/parallels/prl-devops-service/blob/main/src/restapi/controllers.go): `src/restapi/controllers.go`
- [Authorization middleware](https://github.com/parallels/prl-devops-service/blob/main/src/restapi/token_authorization_middleware.go): `src/restapi/token_authorization_middleware.go`
- [API controllers](https://github.com/parallels/prl-devops-service/blob/main/src/controllers/main.go): `src/controllers/main.go`

### VM management

- [VM controller](https://github.com/parallels/prl-devops-service/blob/main/src/controllers/machines.go): `src/controllers/machines.go`
- [Parallels service](https://github.com/parallels/prl-devops-service/blob/main/src/serviceprovider/parallelsdesktop/main.go): `src/serviceprovider/parallelsdesktop/main.go`

### Catalog distribution

- [Catalog controllers](https://github.com/parallels/prl-devops-service/blob/main/src/controllers/catalog.go): `src/controllers/catalog.go`
- [Manager controllers](https://github.com/parallels/prl-devops-service/blob/main/src/controllers/catalog_managers.go): `src/controllers/catalog_managers.go`
- [Catalog service](https://github.com/parallels/prl-devops-service/blob/main/src/catalog/main.go): `src/catalog/main.go`
- [Storage providers](https://github.com/parallels/prl-devops-service/blob/main/src/catalog/providers/local/main.go): `src/catalog/providers/local/main.go`
- [Catalog cache](https://github.com/parallels/prl-devops-service/blob/main/src/catalog/cacheservice/main.go): `src/catalog/cacheservice/main.go`

### Host orchestration

- [Orchestrator operations](https://github.com/parallels/prl-devops-service/blob/main/src/orchestrator/main.go): `src/orchestrator/main.go`
- [Host WebSocket manager](https://github.com/parallels/prl-devops-service/blob/main/src/orchestrator/host_websocket_manager.go): `src/orchestrator/host_websocket_manager.go`

### State and integrations

- [Job tracking](https://github.com/parallels/prl-devops-service/blob/main/src/jobs/main.go): `src/jobs/main.go`
- [Reverse proxy](https://github.com/parallels/prl-devops-service/blob/main/src/reverse_proxy/main.go): `src/reverse_proxy/main.go`
- [Data access](https://github.com/parallels/prl-devops-service/blob/main/src/data/main.go): `src/data/main.go`
- [JSON database](https://github.com/parallels/prl-devops-service/blob/main/src/data/main.go): `src/data/main.go`
- [SQL service](https://github.com/parallels/prl-devops-service/blob/main/src/sql/service.go): `src/sql/service.go`
- [Event emitter](https://github.com/parallels/prl-devops-service/blob/main/src/serviceprovider/eventEmitter/main.go): `src/serviceprovider/eventEmitter/main.go`

### Other components

- **API client**
- **Managed host**

## Connections

- API client → REST API: sends request
- REST API → Authorization middleware: authorizes
- REST API → API controllers: dispatches
- API controllers → VM controller: routes VM requests
- VM controller → Parallels service: manages VMs
- API controllers → Catalog controllers: routes catalog requests
- API controllers → Manager controllers: routes manager requests
- Manager controllers → Data access: reads and writes
- Manager controllers → Job tracking: creates catalog job
- Catalog controllers → Catalog service: catalog operations
- Catalog service → Storage providers: uses provider
- Catalog service → Catalog cache: uses cache
- Orchestrator operations → Data access: loads host state
- Orchestrator operations → Host WebSocket manager: manages host connections
- Host WebSocket manager → Managed host: connects
- Host WebSocket manager → Data access: updates connection status
- Reverse proxy → Parallels service: resolves VM targets
- Data access → JSON database: accesses JSON store
- Data access → SQL service: uses SQL service
- Parallels service → Event emitter: broadcasts VM updates