# oneprolabs/hypercdr architecture

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

- Interactive diagram: https://gitdiagram.com/oneprolabs/hypercdr
- Repository: https://github.com/oneprolabs/hypercdr
- Video tour (about a minute): https://gitdiagram.com/oneprolabs/hypercdr/video

## Overview

HyperCDR is a Kubernetes application disaster-recovery control plane. Its principal workflow runs from cluster registration and inventory discovery through protection configuration, scheduled or manual synchronization, persisted task dispatch, restore-point tracking, and target-cluster recovery. The graph combines README-described behavior with sampled implementation; unsampled subsystem links are shown only where the README explicitly documents them.

Main entry points: [`backend/internal/store/postgres.go`](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/store/postgres.go) (PostgreSQL store), [`agent/comm-agent/internal/wsclient/client.go`](https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/wsclient/client.go) (Secure connection), [`backend/internal/httpserver/router.go`](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/router.go) (HTTP API), [`backend/internal/httpserver/task_dispatch.go`](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/task_dispatch.go) (Task dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_app["Platform UI<br/>[App.tsx]"]
  node_cluster_ui["Cluster views<br/>[cluster-page.tsx]"]
  node_policy_ui["Protection plans<br/>[policy-page.tsx]"]
  node_recovery_ui["Recovery workflows<br/>[task-ui.tsx]"]
end

subgraph group_control["Control plane"]
  node_api["HTTP API<br/>[router.go]"]
  node_registration["Cluster registration"]
  node_discovery["Inventory handlers"]
  node_plans["Plan handlers"]
  node_scheduler["Protection scheduler<br/>[scheduler.go]"]
  node_dispatch["Task dispatch<br/>[task_dispatch.go]"]
  node_backup_handlers["Backup handlers<br/>[backup_handlers.go]"]
  node_recovery_handlers["Recovery handlers"]
  node_storage_handlers["Storage management"]
  node_store[("PostgreSQL store<br/>[postgres.go]")]
  node_secret_crypto["Credential encryption<br/>[storage_crypto.go]"]
end

subgraph group_agent["Cluster agent"]
  node_agent["comm-agent<br/>[main.go]"]
  node_ws["Secure connection<br/>[client.go]"]
  node_inventory["Cluster inventory<br/>[collector.go]"]
  node_backup_exec["Backup execution<br/>[backup.go]"]
  node_restore_exec["Restore execution<br/>[restore.go]"]
  node_storage_exec["Storage execution<br/>[storage.go]"]
end

subgraph group_protection["Protection runtime"]
  node_velero["Velero integration<br/>[backup.go]"]
  node_kube["Kubernetes operations<br/>[dynamic_applier.go]"]
end

node_browser(("Browser user"))
node_cluster_api{{"Kubernetes API"}}
node_velero_engine{{"Velero engine"}}
node_object_storage[("Object storage")]
node_postgres[("PostgreSQL")]

node_browser -->|"uses"| node_app
node_app -->|"REST requests"| node_api
node_app -->|"renders"| node_cluster_ui
node_app -->|"renders"| node_policy_ui
node_app -->|"renders"| node_recovery_ui
node_cluster_ui -->|"manages clusters"| node_api
node_policy_ui -->|"configures protection"| node_api
node_recovery_ui -->|"requests recovery"| node_api
node_api -->|"routes registration"| node_registration
node_registration -->|"persists cluster"| node_store
node_api -->|"routes inventory"| node_discovery
node_discovery -->|"persists inventory"| node_store
node_api -->|"routes plans"| node_plans
node_plans -->|"persists plans"| node_store
node_scheduler -->|"reads due plans"| node_store
node_scheduler -->|"creates scheduled tasks"| node_dispatch
node_backup_handlers -->|"creates backup tasks"| node_dispatch
node_recovery_handlers -->|"creates recovery tasks"| node_dispatch
node_storage_handlers -->|"manages repositories"| node_store
node_store -->|"protects credentials"| node_secret_crypto
node_store -->|"reads and writes"| node_postgres
node_dispatch -->|"persists tasks"| node_store
node_dispatch -->|"sends task"| node_ws
node_agent -->|"registers and reconnects"| node_ws
node_ws -->|"requests discovery"| node_inventory
node_inventory -->|"reads resources"| node_cluster_api
node_ws -->|"executes backup"| node_backup_exec
node_ws -->|"executes restore"| node_restore_exec
node_ws -->|"executes storage sync"| node_storage_exec
node_backup_exec -->|"builds backup operations"| node_velero
node_restore_exec -->|"builds restore operations"| node_velero
node_storage_exec -->|"builds storage manifests"| node_velero
node_storage_exec -->|"applies manifests"| node_kube
node_velero -->|"coordinates protection"| node_velero_engine
node_kube -->|"applies resources"| node_cluster_api
node_velero_engine -->|"stores backup data"| node_object_storage
node_ws -->|"reports progress"| node_dispatch
node_dispatch -->|"updates task state"| node_store
node_backup_handlers -->|"records restore points"| node_store
node_recovery_handlers -->|"tracks recovery state"| node_store

click node_app "https://github.com/oneprolabs/hypercdr/blob/main/frontend/src/App.tsx"
click node_cluster_ui "https://github.com/oneprolabs/hypercdr/blob/main/frontend/src/features/clusters/cluster-page.tsx"
click node_policy_ui "https://github.com/oneprolabs/hypercdr/blob/main/frontend/src/features/policies/policy-page.tsx"
click node_recovery_ui "https://github.com/oneprolabs/hypercdr/blob/main/frontend/src/features/recovery/task-ui.tsx"
click node_api "https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/router.go"
click node_registration "https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/agent_registration_handlers.go"
click node_discovery "https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/cluster_handlers.go"
click node_plans "https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/protection_plan_handlers.go"
click node_scheduler "https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/scheduler.go"
click node_dispatch "https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/task_dispatch.go"
click node_backup_handlers "https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/backup_handlers.go"
click node_recovery_handlers "https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/recovery_handlers.go"
click node_storage_handlers "https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/storage_handlers.go"
click node_store "https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/store/postgres.go"
click node_secret_crypto "https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/store/storage_crypto.go"
click node_agent "https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/cmd/comm-agent/main.go"
click node_ws "https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/wsclient/client.go"
click node_inventory "https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/inventory/collector.go"
click node_backup_exec "https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/executor/backup.go"
click node_restore_exec "https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/executor/restore.go"
click node_storage_exec "https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/executor/storage.go"
click node_velero "https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/velero/backup.go"
click node_kube "https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/kube/dynamic_applier.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_app,node_cluster_ui,node_policy_ui,node_recovery_ui,node_browser toneBlue
class node_api,node_registration,node_discovery,node_plans,node_scheduler,node_dispatch,node_backup_handlers,node_recovery_handlers,node_storage_handlers,node_store,node_secret_crypto,node_object_storage,node_postgres toneAmber
class node_agent,node_ws,node_inventory,node_backup_exec,node_restore_exec,node_storage_exec,node_cluster_api toneMint
class node_velero,node_kube toneRose
class node_velero_engine toneIndigo
```

## Components

### User interface

- [Platform UI](https://github.com/oneprolabs/hypercdr/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Cluster views](https://github.com/oneprolabs/hypercdr/blob/main/frontend/src/features/clusters/cluster-page.tsx): `frontend/src/features/clusters/cluster-page.tsx`
- [Protection plans](https://github.com/oneprolabs/hypercdr/blob/main/frontend/src/features/policies/policy-page.tsx): `frontend/src/features/policies/policy-page.tsx`
- [Recovery workflows](https://github.com/oneprolabs/hypercdr/blob/main/frontend/src/features/recovery/task-ui.tsx): `frontend/src/features/recovery/task-ui.tsx`

### Control plane

- [HTTP API](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/router.go): `backend/internal/httpserver/router.go`
- [Cluster registration](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/agent_registration_handlers.go): `backend/internal/httpserver/agent_registration_handlers.go`
- [Inventory handlers](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/cluster_handlers.go): `backend/internal/httpserver/cluster_handlers.go`
- [Plan handlers](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/protection_plan_handlers.go): `backend/internal/httpserver/protection_plan_handlers.go`
- [Protection scheduler](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/scheduler.go): `backend/internal/httpserver/scheduler.go`
- [Task dispatch](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/task_dispatch.go): `backend/internal/httpserver/task_dispatch.go`
- [Backup handlers](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/backup_handlers.go): `backend/internal/httpserver/backup_handlers.go`
- [Recovery handlers](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/recovery_handlers.go): `backend/internal/httpserver/recovery_handlers.go`
- [Storage management](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/httpserver/storage_handlers.go): `backend/internal/httpserver/storage_handlers.go`
- [PostgreSQL store](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/store/postgres.go): `backend/internal/store/postgres.go`
- [Credential encryption](https://github.com/oneprolabs/hypercdr/blob/main/backend/internal/store/storage_crypto.go): `backend/internal/store/storage_crypto.go`

### Cluster agent

- [comm-agent](https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/cmd/comm-agent/main.go): `agent/comm-agent/cmd/comm-agent/main.go`
- [Secure connection](https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/wsclient/client.go): `agent/comm-agent/internal/wsclient/client.go`
- [Cluster inventory](https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/inventory/collector.go): `agent/comm-agent/internal/inventory/collector.go`
- [Backup execution](https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/executor/backup.go): `agent/comm-agent/internal/executor/backup.go`
- [Restore execution](https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/executor/restore.go): `agent/comm-agent/internal/executor/restore.go`
- [Storage execution](https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/executor/storage.go): `agent/comm-agent/internal/executor/storage.go`

### Protection runtime

- [Velero integration](https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/velero/backup.go): `agent/comm-agent/internal/velero/backup.go`
- [Kubernetes operations](https://github.com/oneprolabs/hypercdr/blob/main/agent/comm-agent/internal/kube/dynamic_applier.go): `agent/comm-agent/internal/kube/dynamic_applier.go`

### Other components

- **Browser user**
- **Kubernetes API**
- **Velero engine**
- **Object storage**
- **PostgreSQL**

## Connections

- Browser user → Platform UI: uses
- Platform UI → HTTP API: REST requests
- Platform UI → Cluster views: renders
- Platform UI → Protection plans: renders
- Platform UI → Recovery workflows: renders
- Cluster views → HTTP API: manages clusters
- Protection plans → HTTP API: configures protection
- Recovery workflows → HTTP API: requests recovery
- HTTP API → Cluster registration: routes registration
- Cluster registration → PostgreSQL store: persists cluster
- HTTP API → Inventory handlers: routes inventory
- Inventory handlers → PostgreSQL store: persists inventory
- HTTP API → Plan handlers: routes plans
- Plan handlers → PostgreSQL store: persists plans
- Protection scheduler → PostgreSQL store: reads due plans
- Protection scheduler → Task dispatch: creates scheduled tasks
- Backup handlers → Task dispatch: creates backup tasks
- Recovery handlers → Task dispatch: creates recovery tasks
- Storage management → PostgreSQL store: manages repositories
- PostgreSQL store → Credential encryption: protects credentials
- PostgreSQL store → PostgreSQL: reads and writes
- Task dispatch → PostgreSQL store: persists tasks
- Task dispatch → Secure connection: sends task
- comm-agent → Secure connection: registers and reconnects
- Secure connection → Cluster inventory: requests discovery
- Cluster inventory → Kubernetes API: reads resources
- Secure connection → Backup execution: executes backup
- Secure connection → Restore execution: executes restore
- Secure connection → Storage execution: executes storage sync
- Backup execution → Velero integration: builds backup operations
- Restore execution → Velero integration: builds restore operations
- Storage execution → Velero integration: builds storage manifests
- Storage execution → Kubernetes operations: applies manifests
- Velero integration → Velero engine: coordinates protection
- Kubernetes operations → Kubernetes API: applies resources
- Velero engine → Object storage: stores backup data
- Secure connection → Task dispatch: reports progress
- Task dispatch → PostgreSQL store: updates task state
- Backup handlers → PostgreSQL store: records restore points
- Recovery handlers → PostgreSQL store: tracks recovery state