# ozertugrul/potorix architecture

> Architecture diagram of the GitHub repository ozertugrul/potorix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ozertugrul/potorix
- Repository: https://github.com/ozertugrul/potorix

## Overview

Potorix is a self-hosted KVM/libvirt management control plane. Its main workflow runs from dashboard actions through the VM API and asynchronous job engine to hypervisor operations, with operation state and audit records persisted and results surfaced to the UI. Separate branches cover monitoring, backups and snapshots, app installs, and browser console access. The graph follows the sampled calls and README; some subsystem implementations were not sampled, so their links are documented or marked unverified.

Main entry points: [`app/api/application.rb`](https://github.com/ozertugrul/potorix/blob/main/app/api/application.rb) (REST and console API), [`frontend/src/pages/VmDetailPage.tsx`](https://github.com/ozertugrul/potorix/blob/main/frontend/src/pages/VmDetailPage.tsx) (VM dashboard), [`config/database.rb`](https://github.com/ozertugrul/potorix/blob/main/config/database.rb) (Persistent state), [`frontend/src/hooks/useVmActions.ts`](https://github.com/ozertugrul/potorix/blob/main/frontend/src/hooks/useVmActions.ts) (VM actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["VM dashboard<br/>[VmDetailPage.tsx]"]
  node_create_vm["VM creation<br/>[VmCreateDrawer.tsx]"]
  node_vm_queries["VM queries<br/>[useVmQueries.ts]"]
  node_vm_actions["VM actions<br/>[useVmActions.ts]"]
  node_frontend_api["Backend API client<br/>[backendVmApi.ts]"]
  node_vm_state["VM UI state<br/>[vmStore.ts]"]
  node_toasts["Toast notifications<br/>[toastStore.ts]"]
end

subgraph group_api["API and state"]
  node_api_server["REST and console API<br/>[application.rb]"]
  node_auth["API-key auth<br/>[api_key_auth.rb]"]
  node_operation_store["Operation tracking<br/>[operation_store.rb]"]
  node_audit["Audit logging<br/>[audit_logger.rb]"]
  node_db[("Persistent state<br/>[database.rb]")]
  node_realtime["Realtime events<br/>[realtime_stream.rb]"]
end

subgraph group_workers["Worker engine"]
  node_lifecycle_job["VM lifecycle jobs"]
  node_backup_job["Backup runs<br/>[backup_run_job.rb]"]
  node_scheduler["Backup scheduler<br/>[scheduler_job.rb]"]
  node_marketplace_job["App installs"]
  node_metrics_job["Metrics collection"]
end

subgraph group_integrations["Host integrations"]
  node_virsh["Virsh adapter<br/>[virsh_adapter.rb]"]
  node_libvirt["KVM/libvirt host"]
  node_redis[("Redis cache and events")]
  node_vnc["VNC proxy and console<br/>[novnc.html]"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"loads data"| node_vm_queries
node_dashboard -->|"dispatches actions"| node_vm_actions
node_dashboard -->|"opens creation"| node_create_vm
node_vm_actions -->|"submits action"| node_frontend_api
node_vm_queries -->|"fetches data"| node_frontend_api
node_vm_actions -->|"sets loading"| node_vm_state
node_vm_actions -->|"reports result"| node_toasts
node_create_vm -->|"creates VM"| node_frontend_api
node_create_vm -->|"reports result"| node_toasts
node_frontend_api -.->|"HTTP requests"| node_api_server
node_api_server -->|"authorizes requests"| node_auth
node_api_server -->|"enqueues operations"| node_lifecycle_job
node_api_server -->|"records operations"| node_operation_store
node_api_server -->|"reads and writes"| node_db
node_lifecycle_job -->|"executes VM actions"| node_virsh
node_lifecycle_job -->|"updates status"| node_operation_store
node_lifecycle_job -->|"records outcome"| node_audit
node_virsh -->|"controls hypervisor"| node_libvirt
node_operation_store -->|"persists operations"| node_db
node_operation_store -->|"publishes events"| node_realtime
node_audit -.->|"stores audit records"| node_db
node_realtime -.->|"distributes events"| node_redis
node_metrics_job -->|"samples VM stats"| node_libvirt
node_metrics_job -->|"stores metrics"| node_db
node_metrics_job -->|"caches samples"| node_redis
node_vm_queries -->|"supplies metrics"| node_dashboard
node_backup_job -.->|"performs backup work"| node_virsh
node_scheduler -.->|"schedules runs"| node_backup_job
node_marketplace_job -.->|"tracks installs"| node_db
node_operator -.->|"opens browser console"| node_vnc
node_api_server -.->|"provides console access"| node_vnc

click node_dashboard "https://github.com/ozertugrul/potorix/blob/main/frontend/src/pages/VmDetailPage.tsx"
click node_create_vm "https://github.com/ozertugrul/potorix/blob/main/frontend/src/components/vm/VmCreateDrawer.tsx"
click node_vm_queries "https://github.com/ozertugrul/potorix/blob/main/frontend/src/hooks/useVmQueries.ts"
click node_vm_actions "https://github.com/ozertugrul/potorix/blob/main/frontend/src/hooks/useVmActions.ts"
click node_frontend_api "https://github.com/ozertugrul/potorix/blob/main/frontend/src/services/backendVmApi.ts"
click node_vm_state "https://github.com/ozertugrul/potorix/blob/main/frontend/src/store/vmStore.ts"
click node_toasts "https://github.com/ozertugrul/potorix/blob/main/frontend/src/store/toastStore.ts"
click node_api_server "https://github.com/ozertugrul/potorix/blob/main/app/api/application.rb"
click node_auth "https://github.com/ozertugrul/potorix/blob/main/app/services/auth/api_key_auth.rb"
click node_operation_store "https://github.com/ozertugrul/potorix/blob/main/app/services/operation_store.rb"
click node_audit "https://github.com/ozertugrul/potorix/blob/main/app/services/audit_logger.rb"
click node_db "https://github.com/ozertugrul/potorix/blob/main/config/database.rb"
click node_realtime "https://github.com/ozertugrul/potorix/blob/main/app/services/realtime_stream.rb"
click node_lifecycle_job "https://github.com/ozertugrul/potorix/blob/main/app/jobs/vm_lifecycle_job.rb"
click node_backup_job "https://github.com/ozertugrul/potorix/blob/main/app/jobs/backup_run_job.rb"
click node_scheduler "https://github.com/ozertugrul/potorix/blob/main/app/jobs/scheduler_job.rb"
click node_marketplace_job "https://github.com/ozertugrul/potorix/blob/main/app/jobs/app_marketplace_job.rb"
click node_metrics_job "https://github.com/ozertugrul/potorix/blob/main/app/jobs/metrics_collector_job.rb"
click node_virsh "https://github.com/ozertugrul/potorix/blob/main/app/services/hypervisor/virsh_adapter.rb"
click node_vnc "https://github.com/ozertugrul/potorix/blob/main/public/novnc.html"

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_dashboard,node_create_vm,node_vm_queries,node_vm_actions,node_frontend_api,node_vm_state,node_toasts toneBlue
class node_api_server,node_auth,node_operation_store,node_audit,node_db,node_realtime toneAmber
class node_lifecycle_job,node_backup_job,node_scheduler,node_marketplace_job,node_metrics_job toneMint
class node_virsh,node_libvirt,node_redis,node_vnc toneRose
class node_operator toneIndigo
```

## Components

### Dashboard

- [VM dashboard](https://github.com/ozertugrul/potorix/blob/main/frontend/src/pages/VmDetailPage.tsx): `frontend/src/pages/VmDetailPage.tsx`
- [VM creation](https://github.com/ozertugrul/potorix/blob/main/frontend/src/components/vm/VmCreateDrawer.tsx): `frontend/src/components/vm/VmCreateDrawer.tsx`
- [VM queries](https://github.com/ozertugrul/potorix/blob/main/frontend/src/hooks/useVmQueries.ts): `frontend/src/hooks/useVmQueries.ts`
- [VM actions](https://github.com/ozertugrul/potorix/blob/main/frontend/src/hooks/useVmActions.ts): `frontend/src/hooks/useVmActions.ts`
- [Backend API client](https://github.com/ozertugrul/potorix/blob/main/frontend/src/services/backendVmApi.ts): `frontend/src/services/backendVmApi.ts`
- [VM UI state](https://github.com/ozertugrul/potorix/blob/main/frontend/src/store/vmStore.ts): `frontend/src/store/vmStore.ts`
- [Toast notifications](https://github.com/ozertugrul/potorix/blob/main/frontend/src/store/toastStore.ts): `frontend/src/store/toastStore.ts`

### API and state

- [REST and console API](https://github.com/ozertugrul/potorix/blob/main/app/api/application.rb): `app/api/application.rb`
- [API-key auth](https://github.com/ozertugrul/potorix/blob/main/app/services/auth/api_key_auth.rb): `app/services/auth/api_key_auth.rb`
- [Operation tracking](https://github.com/ozertugrul/potorix/blob/main/app/services/operation_store.rb): `app/services/operation_store.rb`
- [Audit logging](https://github.com/ozertugrul/potorix/blob/main/app/services/audit_logger.rb): `app/services/audit_logger.rb`
- [Persistent state](https://github.com/ozertugrul/potorix/blob/main/config/database.rb): `config/database.rb`
- [Realtime events](https://github.com/ozertugrul/potorix/blob/main/app/services/realtime_stream.rb): `app/services/realtime_stream.rb`

### Worker engine

- [VM lifecycle jobs](https://github.com/ozertugrul/potorix/blob/main/app/jobs/vm_lifecycle_job.rb): `app/jobs/vm_lifecycle_job.rb`
- [Backup runs](https://github.com/ozertugrul/potorix/blob/main/app/jobs/backup_run_job.rb): `app/jobs/backup_run_job.rb`
- [Backup scheduler](https://github.com/ozertugrul/potorix/blob/main/app/jobs/scheduler_job.rb): `app/jobs/scheduler_job.rb`
- [App installs](https://github.com/ozertugrul/potorix/blob/main/app/jobs/app_marketplace_job.rb): `app/jobs/app_marketplace_job.rb`
- [Metrics collection](https://github.com/ozertugrul/potorix/blob/main/app/jobs/metrics_collector_job.rb): `app/jobs/metrics_collector_job.rb`

### Host integrations

- [Virsh adapter](https://github.com/ozertugrul/potorix/blob/main/app/services/hypervisor/virsh_adapter.rb): `app/services/hypervisor/virsh_adapter.rb`
- **KVM/libvirt host**
- **Redis cache and events**
- [VNC proxy and console](https://github.com/ozertugrul/potorix/blob/main/public/novnc.html): `public/novnc.html`

### Other components

- **Operator**

## Connections

- Operator → VM dashboard: uses (evidence: `README.md`)
- VM dashboard → VM queries: loads data (evidence: `frontend/src/pages/VmDetailPage.tsx`)
- VM dashboard → VM actions: dispatches actions (evidence: `frontend/src/pages/VmDetailPage.tsx`)
- VM dashboard → VM creation: opens creation (evidence: `frontend/src/pages/VmDetailPage.tsx`)
- VM actions → Backend API client: submits action (evidence: `frontend/src/hooks/useVmActions.ts`)
- VM queries → Backend API client: fetches data (evidence: `frontend/src/hooks/useVmQueries.ts`)
- VM actions → VM UI state: sets loading (evidence: `frontend/src/hooks/useVmActions.ts`)
- VM actions → Toast notifications: reports result (evidence: `frontend/src/hooks/useVmActions.ts`)
- VM creation → Backend API client: creates VM (evidence: `frontend/src/components/vm/VmCreateDrawer.tsx`)
- VM creation → Toast notifications: reports result (evidence: `frontend/src/components/vm/VmCreateDrawer.tsx`)
- Backend API client → REST and console API: HTTP requests
- REST and console API → API-key auth: authorizes requests (evidence: `app/api/application.rb`)
- REST and console API → VM lifecycle jobs: enqueues operations (evidence: `app/api/application.rb`)
- REST and console API → Operation tracking: records operations (evidence: `app/api/application.rb`)
- REST and console API → Persistent state: reads and writes (evidence: `app/api/application.rb`)
- VM lifecycle jobs → Virsh adapter: executes VM actions (evidence: `app/jobs/vm_lifecycle_job.rb`)
- VM lifecycle jobs → Operation tracking: updates status (evidence: `app/jobs/vm_lifecycle_job.rb`)
- VM lifecycle jobs → Audit logging: records outcome (evidence: `app/jobs/vm_lifecycle_job.rb`)
- Virsh adapter → KVM/libvirt host: controls hypervisor (evidence: `README.md`)
- Operation tracking → Persistent state: persists operations (evidence: `app/services/operation_store.rb`)
- Operation tracking → Realtime events: publishes events (evidence: `app/services/operation_store.rb`)
- Audit logging → Persistent state: stores audit records
- Realtime events → Redis cache and events: distributes events (evidence: `README.md`)
- Metrics collection → KVM/libvirt host: samples VM stats (evidence: `app/jobs/metrics_collector_job.rb`)
- Metrics collection → Persistent state: stores metrics (evidence: `app/jobs/metrics_collector_job.rb`)
- Metrics collection → Redis cache and events: caches samples (evidence: `app/jobs/metrics_collector_job.rb`)
- VM queries → VM dashboard: supplies metrics (evidence: `frontend/src/pages/VmDetailPage.tsx`)
- Backup runs → Virsh adapter: performs backup work
- Backup scheduler → Backup runs: schedules runs (evidence: `config/sidekiq.rb`)
- App installs → Persistent state: tracks installs
- Operator → VNC proxy and console: opens browser console (evidence: `README.md`)
- REST and console API → VNC proxy and console: provides console access (evidence: `README.md`)