# khryptorgraphics/novacron architecture

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

- Interactive diagram: https://gitdiagram.com/khryptorgraphics/novacron
- Repository: https://github.com/khryptorgraphics/novacron

## Overview

NovaCron’s documented product is a KVM VM manager whose canonical api-server coordinates a peer-to-peer fabric: clients request node/job/transfer operations, the server admits peers and measures links, places work, dispatches transfers or migrations, and exposes usage metering. Authentication and access control protect the API; PostgreSQL persists operational state. The tree omits the documented VM runtime source directory, so VM execution is represented only by the available transfer/migration control component. The README supports the principal relationships; other substantial AI, backup, monitoring, and cloud libraries are explicitly described as unwired from the canonical binary.

Main entry points: [`backend/cmd/api-server/main.go`](https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/main.go) (API server), [`backend/cmd/api-server/cluster_join.go`](https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/cluster_join.go) (Peer admission), [`cli/cmd/novacron/main.go`](https://github.com/khryptorgraphics/novacron/blob/main/cli/cmd/novacron/main.go) (Fabric CLI), [`sdk/typescript/src/client.ts`](https://github.com/khryptorgraphics/novacron/blob/main/sdk/typescript/src/client.ts) (TypeScript SDK)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surface["User surfaces"]
  node_cli["Fabric CLI<br/>[main.go]"]
  node_typescript["TypeScript SDK<br/>[client.ts]"]
  node_web["Fabric UI"]
end

subgraph group_control["Fabric control plane"]
  node_api["API server<br/>[main.go]"]
  node_membership["Peer admission<br/>[cluster_join.go]"]
  node_links["Link telemetry<br/>[cluster_join.go]"]
  node_placement["Job placement<br/>[fabric_jobs.go]"]
  node_transfers["Transfers and migration"]
  node_metering["Usage metering<br/>[billing_usage.go]"]
end

subgraph group_security["Identity and access"]
  node_auth["Authentication<br/>[auth.go]"]
  node_rbac["API access control<br/>[handlers.go]"]
end

subgraph group_state["Persistence"]
  node_postgres[("PostgreSQL")]
end

node_operator(("Operator"))
node_peer(("Fabric peer"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"calls API"| node_api
node_operator -->|"uses SDK"| node_typescript
node_typescript -->|"calls API"| node_api
node_operator -->|"uses UI"| node_web
node_web -->|"uses fabric API"| node_api
node_api -->|"authenticates requests"| node_auth
node_api -->|"routes security API"| node_rbac
node_api -->|"admits peers"| node_membership
node_membership -->|"checks reachability"| node_peer
node_api -->|"measures links"| node_links
node_api -->|"dispatches jobs"| node_placement
node_placement -->|"places workload"| node_peer
node_api -->|"coordinates migration"| node_transfers
node_transfers -->|"transfers VM"| node_peer
node_api -->|"serves usage"| node_metering
node_membership -->|"persists link profiles"| node_postgres
node_metering -->|"writes usage events"| node_postgres

click node_cli "https://github.com/khryptorgraphics/novacron/blob/main/cli/cmd/novacron/main.go"
click node_typescript "https://github.com/khryptorgraphics/novacron/blob/main/sdk/typescript/src/client.ts"
click node_web "https://github.com/khryptorgraphics/novacron/blob/main/frontend/src/components/storage/StorageManagementUI.tsx"
click node_api "https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/main.go"
click node_membership "https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/cluster_join.go"
click node_links "https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/cluster_join.go"
click node_placement "https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/fabric_jobs.go"
click node_transfers "https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/fabric_transfers.go"
click node_metering "https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/billing_usage.go"
click node_auth "https://github.com/khryptorgraphics/novacron/blob/main/backend/core/auth/auth.go"
click node_rbac "https://github.com/khryptorgraphics/novacron/blob/main/backend/api/security/handlers.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_cli,node_typescript,node_web toneBlue
class node_api,node_membership,node_links,node_placement,node_transfers,node_metering toneAmber
class node_auth,node_rbac toneMint
class node_postgres toneRose
class node_operator,node_peer toneIndigo
```

## Components

### User surfaces

- [Fabric CLI](https://github.com/khryptorgraphics/novacron/blob/main/cli/cmd/novacron/main.go): `cli/cmd/novacron/main.go`
- [TypeScript SDK](https://github.com/khryptorgraphics/novacron/blob/main/sdk/typescript/src/client.ts): `sdk/typescript/src/client.ts`
- [Fabric UI](https://github.com/khryptorgraphics/novacron/blob/main/frontend/src/components/storage/StorageManagementUI.tsx): `frontend/src/components/storage/StorageManagementUI.tsx`

### Fabric control plane

- [API server](https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/main.go): `backend/cmd/api-server/main.go`
- [Peer admission](https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/cluster_join.go): `backend/cmd/api-server/cluster_join.go`
- [Link telemetry](https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/cluster_join.go): `backend/cmd/api-server/cluster_join.go`
- [Job placement](https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/fabric_jobs.go): `backend/cmd/api-server/fabric_jobs.go`
- [Transfers and migration](https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/fabric_transfers.go): `backend/cmd/api-server/fabric_transfers.go`
- [Usage metering](https://github.com/khryptorgraphics/novacron/blob/main/backend/cmd/api-server/billing_usage.go): `backend/cmd/api-server/billing_usage.go`

### Identity and access

- [Authentication](https://github.com/khryptorgraphics/novacron/blob/main/backend/core/auth/auth.go): `backend/core/auth/auth.go`
- [API access control](https://github.com/khryptorgraphics/novacron/blob/main/backend/api/security/handlers.go): `backend/api/security/handlers.go`

### Persistence

- **PostgreSQL**

### Other components

- **Operator**
- **Fabric peer**

## Connections

- Operator → Fabric CLI: runs commands (evidence: `README.md`)
- Fabric CLI → API server: calls API (evidence: `README.md`)
- Operator → TypeScript SDK: uses SDK (evidence: `README.md`)
- TypeScript SDK → API server: calls API (evidence: `README.md`)
- Operator → Fabric UI: uses UI (evidence: `README.md`)
- Fabric UI → API server: uses fabric API (evidence: `README.md`)
- API server → Authentication: authenticates requests (evidence: `backend/cmd/api-server/main.go`)
- API server → API access control: routes security API (evidence: `backend/cmd/api-server/main.go`)
- API server → Peer admission: admits peers (evidence: `README.md`)
- Peer admission → Fabric peer: checks reachability (evidence: `README.md`)
- API server → Link telemetry: measures links (evidence: `README.md`)
- API server → Job placement: dispatches jobs (evidence: `README.md`)
- Job placement → Fabric peer: places workload (evidence: `README.md`)
- API server → Transfers and migration: coordinates migration (evidence: `README.md`)
- Transfers and migration → Fabric peer: transfers VM (evidence: `README.md`)
- API server → Usage metering: serves usage (evidence: `README.md`)
- Peer admission → PostgreSQL: persists link profiles (evidence: `README.md`)
- Usage metering → PostgreSQL: writes usage events (evidence: `README.md`)