# Audoryx maintenance archives

The admin maintenance screen creates protected ZIP backups below `storage/app/private/maintenance/archives`. A backup contains:

- one NDJSON stream and column manifest for every database table;
- media from the local public, private, and configured Audoryx media roots;
- a secret-free configuration fingerprint and runtime manifest;
- `backup-manifest.json`, plus a SHA-256 stored in the database and rechecked on download.

Remote object storage is referenced by database records but is not copied into a local ZIP. Mirror remote buckets using the storage provider's versioning/replication feature.

## Update package format

An update ZIP must contain `audoryx-update.json` at its root and every application file below `payload/`. Paths are allowlisted; `.env`, `storage`, `vendor`, `node_modules`, absolute paths, traversal, duplicate paths, and undeclared files are rejected.

```json
{
  "format": "audoryx-update",
  "format_version": 1,
  "version": "1.1.0",
  "minimum_php": "8.2.0",
  "payload_checksum": "sha256-of-sorted-path-and-hash-lines",
  "files": [
    {"path": "app/Example.php", "sha256": "file-sha256"},
    {"path": "database/migrations/2026_08_01_000000_example.php", "sha256": "file-sha256"}
  ],
  "delete": ["resources/js/obsolete.ts"]
}
```

`payload_checksum` is SHA-256 over the declared files sorted by path, joined by a newline in the form `path:sha256`. The distributor should also publish the SHA-256 of the complete ZIP; administrators can provide it in the optional archive checksum field.

Installation performs preflight and checksum validation, creates a full pre-update backup, stages every file, records rollback copies, enables Laravel maintenance mode, applies files, runs `php artisan migrate --force`, clears optimized caches, and restores the previous files if installation fails. Database migrations should be backward-compatible because an arbitrary migration cannot always be rolled back safely after partial external side effects.