PVE-Backup-Report/docs/en/architecture.md

Target Architecture

Version francaise

Overview

The application is a batch tool designed to run once per day. It collects data from the Proxmox VE API, transforms it into internal objects, computes backup coverage, then generates a timestamped PDF report.

The Docker container runs a single command and exits with an explicit return code.

Current repository state: the CLI, configuration, logging, PVE/PBS collection, coverage analysis and WeasyPrint PDF generation are implemented. The Docker container includes the system dependencies required for PDF rendering.

Components

CLI

The CLI is the script entry point.

Responsibilities:

• load configuration;
• initialize logging;
• run collection;
• run analysis;
• generate the PDF;
• return an appropriate exit code.

Configuration

The configuration module reads environment variables and validates required values.

It must not contain API call logic.

PVE Client

The PVE client encapsulates HTTP calls to the Proxmox VE API.

The client uses requests and a reusable session.

It implements:

• API token authentication;
• configurable TLS verification;
• optional CA bundle;
• network timeout;
• dedicated errors for connection, HTTP and invalid response failures;
• verification methods for /nodes, /storage and /cluster/backup.

It handles:

• base URL;
• token authentication;
• TLS verification;
• HTTP errors;
• timeouts;
• JSON deserialization.

Collectors

Collectors retrieve raw information:

• storages;
• backup jobs;
• cluster resources;
• useful VM and CT information;
• VM/CT notes from their node-local configuration;
• PBS prune jobs, when PBS collection is configured;
• PBS snapshots by datastore and namespace, when the corresponding PBS collection is configured.

Each collector must return structured data, not raw JSON scattered across the application.

Current state: collection of PBS storages via /storage, backup jobs via /cluster/backup, VM/CT via /cluster/resources, pools via /pools, latest vzdump tasks via /cluster/tasks and /nodes/{node}/tasks, plus prune jobs and snapshots via the PBS API, is implemented.

Models

Models represent internal entities:

• PbsStorage;
• PbsRetentionPolicy;
• PbsBackupSnapshotSummary;
• Guest;
• BackupJob;
• BackupCoverage;
• ReportData;
• ReportSummary;
• CollectionIssue.

Models can be implemented with dataclasses or Pydantic depending on project choices.

Coverage Analysis

The analysis module compares the VM/CT inventory with active backup jobs.

It produces one status per VM/CT:

• sauvegarde_planifiee;
• non_sauvegardee;
• indetermine.

Current state: coverage based on explicitly listed vmid values, all=1 and pool=<name> is computed. Simple exclusions are handled.

PDF Generation

The PDF generator receives a complete ReportData object and produces a file.

It must not call the PVE API.

It must not reread global configuration except for strictly necessary rendering options.

The main renderer uses WeasyPrint from an HTML/CSS template. This keeps business logic separate from presentation and makes visual changes easier.

The PDF currently contains the summary, PBS storages declared in PVE, PBS storage usage, PBS retention policies, backup jobs, VM/CT without backup, VM/CT coverage, VM/CT backup retention by PBS with expected version count and delta, and anomalies.

Data Flow

1. Load configuration.
2. Connect to the PVE API.
3. Optionally connect to configured PBS APIs.
4. Collect storages.
5. Filter PBS storages.
6. Collect prune jobs and snapshots, if configured.
7. Collect backup jobs.
8. Collect VMs and CTs.
9. Compute coverage.
10. Build the report model.
11. Generate the PDF.
12. Log result and exit code.

A preparation step assembles a final ReportData object with a computed ReportSummary. The --dump-report-data command previews this model as JSON.

The --generate-pdf command renders this model as a PDF with WeasyPrint. With Docker Compose, it must be launched explicitly:

docker compose run --rm pve-backup-report --generate-pdf

Error Handling

Blocking errors stop execution:

• invalid configuration;
• authentication failure;
• PVE API fully unavailable;
• inability to write the PDF.

Partial errors can be added to the report:

• a node does not respond;
• an expected field is missing;
• a job cannot be interpreted;
• a referenced storage is missing from collection.

Idempotence

Daily execution must not modify PVE state.

The tool is read-only with regard to the cluster.

The only expected side effect is the creation of a new report in the output directory.