# pkanderi-abio/vmware-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/pkanderi-abio/vmware-dashboard
- Repository: https://github.com/pkanderi-abio/vmware-dashboard

## Overview

#### Purpose and Entry Points
VMware Dashboard is a full-stack operations dashboard for monitoring multiple vCenter environments and enriching VM inventory with historical CMDB and optional PuppetDB data. The backend FastAPI application starts at `main.py`; the React/Vite SPA starts at `src/main.tsx` and composes routes in `src/App.tsx`.

#### Backend API and Application Boundary
`main.py` is the API boundary for browser clients: it exposes inventory, configuration, health, search, action, CMDB, and integration endpoints, applies CORS, and coordinates backend services. Browser API targeting is centralized in `src/config/api.ts` and consumed through `src/lib/api.ts`; the frontend supports a runtime backend URL override rather than requiring rebuilds.

#### vCenter Connection and Collection Pipeline
vCenter endpoints and server-local credentials are managed through the backend, with credentials persisted outside the repository under the user cache directory. Parallel pyVmomi PropertyCollector-based inventory gathering is implemented in `vcenter_fast.py`; related VMware domains are separated into lifecycle, tags, certificate, and health modules:
- `vcenter_fast.py`
- `vcenter_health.py`
- `vcenter_lifecycle.py`
- `vcenter_tags.py`
- `vcenter_certs.py`

The collector is the core external-system boundary to vCenter over HTTPS/443 and supplies hosts, VMs, datastores, networks, and snapshots for API responses.

#### Inventory, Cache, and Operational Actions
The backend converts collected vCenter state into dashboard resources, supports cached refresh behavior, and retains historical CMDB state for decommission tracking. `cmdb_history.py` owns inventory history; `global_search.py` provides cross-resource search; `action_guard.py` gates operational actions before they reach VMware-facing logic. Snapshot and VM action affordances are surfaced from:
- `src/components/vm-actions.tsx`
- `src/components/snapshot-actions.tsx`
- `src/pages/snapshots.tsx`

#### CMDB and Puppet Enrichment
CMDB records combine vCenter VM facts with optional PuppetDB data, allowing detail views and exports to show operational classification, facts, and history. `puppet_client.py` is the PuppetDB REST boundary, while `cmdb_history.py` persists local historical state. Primary UI consumers are:
- `src/pages/cmdb.tsx`
- `src/pages/vm-detail.tsx`
- `puppet_client.py`

#### Frontend Presentation and Navigation
The SPA uses React 18, TypeScript, React Router, Tailwind, and shadcn-style components. The app shell/sidebar and global search live in `src/pages/_layout.tsx`; resource pages render independent inventory perspectives, notably `src/pages/index.tsx`, `src/pages/vms.tsx`, `src/pages/hosts.tsx`, and `src/pages/observability.tsx`. Theme state persists client-side via `src/lib/theme.tsx`.

#### Deployment and Runtime Infrastructure
Backend runtime is Python 3.9+ with FastAPI/Uvicorn and pyVmomi; frontend is built by Vite and served as static assets or behind a reverse proxy. Container builds are split by tier in `docker/api.Dockerfile` and `docker/frontend.Dockerfile`. Kubernetes manifests define API/frontend deployments, ingress, persistent storage, HPA, network policy, secrets, and an in-cluster runner:
- `k8s/kustomization.yaml`
- `k8s/api-deployment.yaml`
- `k8s/frontend-deployment.yaml`
- `k8s/runner/deployment.yaml`

GitHub Actions validates frontend builds and supports self-hosted-runner deployment through `.github/workflows/ci.yml` and `.github/workflows/deploy.yml`.

Main entry points: [`main.py`](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/main.py) (API application), [`src/pages/_layout.tsx`](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/pages/_layout.tsx) (Shell, sidebar & search), [`k8s/kustomization.yaml`](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/k8s/kustomization.yaml) (Kubernetes deployment), [`src/config/api.ts`](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/config/api.ts) (API client & runtime URL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_spa_entry["SPA entry<br/>React entry<br/>[main.tsx]"]
  node_app_routes["App routes<br/>React Router<br/>[App.tsx]"]
  node_app_shell["Shell, sidebar &amp; search<br/>layout<br/>[_layout.tsx]"]
  node_inventory_pages["Inventory views<br/>React pages<br/>[index.tsx]"]
  node_cmdb_views["CMDB &amp; VM detail<br/>React pages<br/>[cmdb.tsx]"]
  node_actions_ui["VM &amp; snapshot actions<br/>React components<br/>[vm-actions.tsx]"]
  node_api_client["API client &amp; runtime URL<br/>frontend API layer<br/>[api.ts]"]
  node_theme_state["Theme state<br/>client persistence<br/>[theme.tsx]"]
end

subgraph group_backend["FastAPI backend"]
  node_api_app["API application<br/>FastAPI<br/>[main.py]"]
  node_vcenter_collector["Parallel inventory collector<br/>pyVmomi PropertyCollector<br/>[vcenter_fast.py]"]
  node_vcenter_domains["vCenter domain services<br/>VMware services<br/>[vcenter_health.py]"]
  node_action_guard["Action guard<br/>operation policy<br/>[action_guard.py]"]
  node_global_search["Global search<br/>search service<br/>[global_search.py]"]
  node_cmdb_history[("CMDB history<br/>local history store<br/>[cmdb_history.py]")]
  node_puppet_client["PuppetDB client<br/>REST client<br/>[puppet_client.py]"]
end

subgraph group_external["Data systems"]
  node_vcenter{{"vCenter environments<br/>external VMware API"}}
  node_puppetdb{{"Optional PuppetDB<br/>external REST API"}}
  node_credential_store[("Local credentials<br/>user cache storage")]
end

subgraph group_runtime["Delivery runtime"]
  node_containers["Tiered container builds<br/>Docker<br/>[api.Dockerfile]"]
  node_kubernetes["Kubernetes deployment<br/>Kubernetes manifests<br/>[kustomization.yaml]"]
  node_ci_cd["CI &amp; deployment<br/>GitHub Actions<br/>[ci.yml]"]
end

node_spa_entry -->|"mounts"| node_app_routes
node_app_routes -->|"composes"| node_app_shell
node_app_shell -->|"navigates"| node_inventory_pages
node_app_shell -->|"navigates"| node_cmdb_views
node_app_shell -->|"uses"| node_theme_state
node_inventory_pages -->|"queries"| node_api_client
node_cmdb_views -->|"queries"| node_api_client
node_actions_ui -->|"submits actions"| node_api_client
node_api_client -->|"browser API requests"| node_api_app
node_api_app -->|"serves inventory"| node_vcenter_collector
node_api_app -->|"coordinates VMware domains"| node_vcenter_domains
node_api_app -->|"searches resources"| node_global_search
node_api_app -->|"reads and records history"| node_cmdb_history
node_api_app -->|"enriches CMDB"| node_puppet_client
node_api_app -->|"authorizes actions"| node_action_guard
node_vcenter_collector -->|"collects over HTTPS"| node_vcenter
node_vcenter_domains -->|"manages domains"| node_vcenter
node_action_guard -->|"permits operations"| node_vcenter
node_vcenter_collector -->|"uses credentials"| node_credential_store
node_puppet_client -->|"REST queries"| node_puppetdb
node_containers -->|"produces workload images"| node_kubernetes
node_ci_cd -->|"builds and validates"| node_containers
node_ci_cd -->|"deploys"| node_kubernetes
node_kubernetes -->|"runs API tier"| node_api_app
node_kubernetes -->|"serves frontend tier"| node_spa_entry

click node_spa_entry "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/main.tsx"
click node_app_routes "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/App.tsx"
click node_app_shell "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/pages/_layout.tsx"
click node_inventory_pages "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/pages/index.tsx"
click node_cmdb_views "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/pages/cmdb.tsx"
click node_actions_ui "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/components/vm-actions.tsx"
click node_api_client "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/config/api.ts"
click node_theme_state "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/lib/theme.tsx"
click node_api_app "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/main.py"
click node_vcenter_collector "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/vcenter_fast.py"
click node_vcenter_domains "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/vcenter_health.py"
click node_action_guard "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/action_guard.py"
click node_global_search "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/global_search.py"
click node_cmdb_history "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/cmdb_history.py"
click node_puppet_client "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/puppet_client.py"
click node_containers "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/docker/api.Dockerfile"
click node_kubernetes "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/k8s/kustomization.yaml"
click node_ci_cd "https://github.com/pkanderi-abio/vmware-dashboard/blob/master/.github/workflows/ci.yml"

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_spa_entry,node_app_routes,node_app_shell,node_inventory_pages,node_cmdb_views,node_actions_ui,node_api_client,node_theme_state toneBlue
class node_api_app,node_vcenter_collector,node_vcenter_domains,node_action_guard,node_global_search,node_cmdb_history,node_puppet_client toneAmber
class node_vcenter,node_puppetdb,node_credential_store toneMint
class node_containers,node_kubernetes,node_ci_cd toneRose
```

## Components

### React SPA

- [SPA entry](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/main.tsx): React entry · `src/main.tsx`
- [App routes](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/App.tsx): React Router · `src/App.tsx`
- [Shell, sidebar & search](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/pages/_layout.tsx): layout · `src/pages/_layout.tsx`
- [Inventory views](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/pages/index.tsx): React pages · Dashboard, VM, host, and observability perspectives. · `src/pages/index.tsx`
- [CMDB & VM detail](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/pages/cmdb.tsx): React pages · `src/pages/cmdb.tsx`
- [VM & snapshot actions](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/components/vm-actions.tsx): React components · `src/components/vm-actions.tsx`
- [API client & runtime URL](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/config/api.ts): frontend API layer · Supports runtime backend URL override. · `src/config/api.ts`
- [Theme state](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/src/lib/theme.tsx): client persistence · `src/lib/theme.tsx`

### FastAPI backend

- [API application](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/main.py): FastAPI · CORS-enabled boundary for dashboard APIs. · `main.py`
- [Parallel inventory collector](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/vcenter_fast.py): pyVmomi PropertyCollector · Collects VMs, hosts, datastores, networks, and snapshots. · `vcenter_fast.py`
- [vCenter domain services](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/vcenter_health.py): VMware services · Health, lifecycle, tags, and certificate operations. · `vcenter_health.py`
- [Action guard](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/action_guard.py): operation policy · Gates VMware-facing operational actions. · `action_guard.py`
- [Global search](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/global_search.py): search service · `global_search.py`
- [CMDB history](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/cmdb_history.py): local history store · Retains historical inventory for decommission tracking. · `cmdb_history.py`
- [PuppetDB client](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/puppet_client.py): REST client · `puppet_client.py`

### Data systems

- **vCenter environments**: external VMware API · HTTPS inventory and action boundary.
- **Optional PuppetDB**: external REST API
- **Local credentials**: user cache storage · Server-local vCenter credentials outside the repository.

### Delivery runtime

- [Tiered container builds](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/docker/api.Dockerfile): Docker · Separate API and frontend images. · `docker/api.Dockerfile`
- [Kubernetes deployment](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/k8s/kustomization.yaml): Kubernetes manifests · API/frontend workloads, ingress, storage, policy, HPA, and runner. · `k8s/kustomization.yaml`
- [CI & deployment](https://github.com/pkanderi-abio/vmware-dashboard/blob/master/.github/workflows/ci.yml): GitHub Actions · Build validation and self-hosted-runner deployment. · `.github/workflows/ci.yml`

## Connections

- SPA entry → App routes: mounts
- App routes → Shell, sidebar & search: composes
- Shell, sidebar & search → Inventory views: navigates
- Shell, sidebar & search → CMDB & VM detail: navigates
- Shell, sidebar & search → Theme state: uses
- Inventory views → API client & runtime URL: queries
- CMDB & VM detail → API client & runtime URL: queries
- VM & snapshot actions → API client & runtime URL: submits actions
- API client & runtime URL → API application: browser API requests
- API application → Parallel inventory collector: serves inventory
- API application → vCenter domain services: coordinates VMware domains
- API application → Global search: searches resources
- API application → CMDB history: reads and records history
- API application → PuppetDB client: enriches CMDB
- API application → Action guard: authorizes actions
- Parallel inventory collector → vCenter environments: collects over HTTPS
- vCenter domain services → vCenter environments: manages domains
- Action guard → vCenter environments: permits operations
- Parallel inventory collector → Local credentials: uses credentials
- PuppetDB client → Optional PuppetDB: REST queries
- Tiered container builds → Kubernetes deployment: produces workload images
- CI & deployment → Tiered container builds: builds and validates
- CI & deployment → Kubernetes deployment: deploys
- Kubernetes deployment → API application: runs API tier
- Kubernetes deployment → SPA entry: serves frontend tier