How ozertugrul/potorix works
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: application.rb REST and console API · VmDetailPage.tsx VM dashboard · database.rb Persistent state · useVmActions.ts VM actions
Components 23
Dashboard
- VM dashboard
frontend/src/pages/VmDetailPage.tsx - VM creation
frontend/src/components/vm/VmCreateDrawer.tsx - VM queries
frontend/src/hooks/useVmQueries.ts - VM actions
frontend/src/hooks/useVmActions.ts - Backend API client
frontend/src/services/backendVmApi.ts - VM UI state
frontend/src/store/vmStore.ts - Toast notifications
frontend/src/store/toastStore.ts
API and state
- REST and console API
app/api/application.rb - API-key auth
app/services/auth/api_key_auth.rb - Operation tracking
app/services/operation_store.rb - Audit logging
app/services/audit_logger.rb - Persistent state
config/database.rb - Realtime events
app/services/realtime_stream.rb
Worker engine
- VM lifecycle jobs
app/jobs/vm_lifecycle_job.rb - Backup runs
app/jobs/backup_run_job.rb - Backup scheduler
app/jobs/scheduler_job.rb - App installs
app/jobs/app_marketplace_job.rb - Metrics collection
app/jobs/metrics_collector_job.rb
Host integrations
- Virsh adapter
app/services/hypervisor/virsh_adapter.rb - KVM/libvirt host
- Redis cache and events
- VNC proxy and console
public/novnc.html
Other components
- Operator
Connections 32
- Operator → VM dashboard: uses
README.md - VM dashboard → VM queries: loads data
frontend/src/pages/VmDetailPage.tsx - VM dashboard → VM actions: dispatches actions
frontend/src/pages/VmDetailPage.tsx - VM dashboard → VM creation: opens creation
frontend/src/pages/VmDetailPage.tsx - VM actions → Backend API client: submits action
frontend/src/hooks/useVmActions.ts - VM queries → Backend API client: fetches data
frontend/src/hooks/useVmQueries.ts - VM actions → VM UI state: sets loading
frontend/src/hooks/useVmActions.ts - VM actions → Toast notifications: reports result
frontend/src/hooks/useVmActions.ts - VM creation → Backend API client: creates VM
frontend/src/components/vm/VmCreateDrawer.tsx - VM creation → Toast notifications: reports result
frontend/src/components/vm/VmCreateDrawer.tsx - Backend API client → REST and console API: HTTP requests
- REST and console API → API-key auth: authorizes requests
app/api/application.rb - REST and console API → VM lifecycle jobs: enqueues operations
app/api/application.rb - REST and console API → Operation tracking: records operations
app/api/application.rb - REST and console API → Persistent state: reads and writes
app/api/application.rb - VM lifecycle jobs → Virsh adapter: executes VM actions
app/jobs/vm_lifecycle_job.rb - VM lifecycle jobs → Operation tracking: updates status
app/jobs/vm_lifecycle_job.rb - VM lifecycle jobs → Audit logging: records outcome
app/jobs/vm_lifecycle_job.rb - Virsh adapter → KVM/libvirt host: controls hypervisor
README.md - Operation tracking → Persistent state: persists operations
app/services/operation_store.rb - Operation tracking → Realtime events: publishes events
app/services/operation_store.rb - Audit logging → Persistent state: stores audit records
- Realtime events → Redis cache and events: distributes events
README.md - Metrics collection → KVM/libvirt host: samples VM stats
app/jobs/metrics_collector_job.rb - Metrics collection → Persistent state: stores metrics
app/jobs/metrics_collector_job.rb - Metrics collection → Redis cache and events: caches samples
app/jobs/metrics_collector_job.rb - VM queries → VM dashboard: supplies metrics
frontend/src/pages/VmDetailPage.tsx - Backup runs → Virsh adapter: performs backup work
- Backup scheduler → Backup runs: schedules runs
config/sidekiq.rb - App installs → Persistent state: tracks installs
- Operator → VNC proxy and console: opens browser console
README.md - REST and console API → VNC proxy and console: provides console access
README.md