# StarPost Backend Operations

Documentation formatting follows [the shared Markdown display contract](../../MARKDOWN-DISPLAY-STYLE.md).

## Command summary

Run these commands from `/home/ubuntu/starpost-backend/scripts`.

```text
┌──────────┬─────────────────────────────────────────────┬────────────┐
│ Action   │ Command                                     │ Restart    │
├──────────┼─────────────────────────────────────────────┼────────────┤
│ Full     │ ../tools/verify-server.sh                   │ No         │
├──────────┼─────────────────────────────────────────────┼────────────┤
│ Verify   │ ./deploy-backend-hotfix.sh --verify         │ No         │
├──────────┼─────────────────────────────────────────────┼────────────┤
│ Deploy   │ ./deploy-backend-hotfix.sh                  │ On change  │
├──────────┼─────────────────────────────────────────────┼────────────┤
│ URL bump │ ./deploy-backend-hotfix.sh --url-version    │ On change  │
├──────────┼─────────────────────────────────────────────┼────────────┤
│ Sync OP2 │ ./deploy-backend-hotfix.sh --sync-op2       │ OP2 change │
├──────────┼─────────────────────────────────────────────┼────────────┤
│ DB check │ ./deploy-backend-db-migrations.sh           │ No         │
├──────────┼─────────────────────────────────────────────┼────────────┤
│ DB apply │ ./deploy-backend-db-migrations.sh --apply   │ No         │
└──────────┴─────────────────────────────────────────────┴────────────┘
```

This directory contains the deployment, migration, validation, and maintenance
tools for the StarPost backend.

## Quick start

### Complete backend verification

From `/home/ubuntu/starpost-backend`:

> `./tools/verify-server.sh`

This is the complete read-only server check. It validates the application,
PM2, database reads, cron schedulers and history, release state, permissions,
dependencies, documentation, generated filesystem clutter, and local/public
runtime without restarting PM2. It prints the verified project tree before its
final result.

### Read-only compatibility verification

> `./scripts/deploy-backend-hotfix.sh --verify`

Checks the current local and public configuration, every template image, UI
assets, OP2 bundle and fonts. It does not change files or restart PM2.

### 1. Normal backend deployment

> **Primary command — use this for normal backend changes**

> **PRIMARY BACKEND DEPLOYMENT**
>
> `./scripts/deploy-backend-hotfix.sh`

This command:

- Compares staged backend files before changing anything
- Skips unchanged files
- Checks and synchronizes OP2
- Restarts PM2 at most once
- Runs local and public smoke tests
- Restores changed source automatically if deployment fails
- Records the deployment result under `releases/`

Stage backend changes under:

`/home/ubuntu/starpost-backend-hotfix/src/`

If a modified file already exists, place it under that staging directory using
the same `src/` path and run the normal deployment command. For example,
`src/routes/config.js` belongs at
`/home/ubuntu/starpost-backend-hotfix/src/routes/config.js`. `--stage-edit` is
not required when the modified file is already staged.

To change the template-image URL version without manually editing a file:

> `./scripts/deploy-backend-hotfix.sh --url-version`

The command displays the current version, suggests the next version, and stages
the change automatically before using the normal deployment checks. It already
compares OP2 and runs the complete compatibility tests, so do not run
`--sync-op2` again afterward.

Only when no prepared file exists and an emergency server-side edit is needed,
use the optional managed editor instead of editing the live file:

> `./scripts/deploy-backend-hotfix.sh --stage-edit src/routes/config.js`

The path identifies the project-relative source to copy; it is not edited
directly. The command opens an isolated staged copy. The original live file is
backed up before installation and is restored automatically if deployment
verification fails.

### 2. OP2 synchronization only

> **Use this when only the frontend OP2 design needs checking or synchronizing**

> **OP2 SYNCHRONIZATION ONLY**
>
> `./scripts/deploy-backend-hotfix.sh --sync-op2`

If the OP2 bundle already matches the active backend bundle, deployment is
skipped and the active version remains unchanged.

### 3. Database and data migrations

> **Preflight only — validates migrations without changing the database**

> **DATABASE MIGRATION PREFLIGHT**
>
> `./scripts/deploy-backend-db-migrations.sh`

> **Apply intentionally — modifies the database and requires typing `MIGRATE`**

> **APPLY DATABASE MIGRATIONS**
>
> `./scripts/deploy-backend-db-migrations.sh --apply`

Migrations are not health checks and should not be run during ordinary
deployments unless the release specifically requires them.

## Directory guide

Paths are relative to `scripts/`.

```text
┌─────────────────────────────────┬──────────────────┬────────────────┐
│ Item                            │ Purpose          │ Manual?        │
├─────────────────────────────────┼──────────────────┼────────────────┤
│ deploy-backend-hotfix.sh        │ Backend + OP2    │ Yes            │
├─────────────────────────────────┼──────────────────┼────────────────┤
│ deploy-backend-db-migrations.sh │ DB migrations    │ When needed    │
├─────────────────────────────────┼──────────────────┼────────────────┤
│ internal/                       │ Internal helpers │ No             │
├─────────────────────────────────┼──────────────────┼────────────────┤
│ migrations/                     │ Migration code   │ Via DB command │
├─────────────────────────────────┼──────────────────┼────────────────┤
│ tools/                          │ Generators/media │ When needed    │
└─────────────────────────────────┴──────────────────┴────────────────┘
```

## Release records

Every deployment attempt is appended to `releases/deployment-runs.jsonl`.

Only a successful deployment containing real changes updates
`releases/current-release.json`. An unchanged check is recorded as `skipped`
and does not create a new release.

The current-release record is the compatibility source of truth. It stores one
release ID together with the active OP2 bundle version and template-image URL
version. These component versions remain independent, while every deployment
validates them together through local and public smoke tests. An unchanged OP2
synchronization also verifies the currently active runtime without restarting
PM2.

Every final result names the operation and outcome, reports the current PM2
status, and states whether PM2 restarted, the exact restart command, and which
subcommand/change triggered it.

## File reference

### `scripts/internal/`

- `deploy-postcard-design.sh` — Builds and atomically activates the OP2 bundle.
- `build-postcard-design.mjs` — Extracts shared postcard design files.
- `bundle-postcard-fonts.mjs` — Downloads and packages canonical OP2 fonts.
- `validate-postcard-design-contract.mjs` — Checks the OP2/backend contract.
- `smoke-test-backend-public-assets.sh` — Tests config, templates and assets.
- `smoke-test-ui-assets.sh` — Tests the UI manifest and listed assets.

### `scripts/migrations/`

- `migrate-qr-artifacts.mjs` — Backfills immutable QR image artifacts.
- `migrate-tax-evidence.mjs` — Migrates VAT and location-evidence data.

### `scripts/tools/`

- `generate-mascot-gifs.mjs` — Generates email mascot animations.
- `generate-stamp-config.mjs` — Generates server stamp settings from CSS.
- `generate-wallet.js` — Creates a blockchain-sealing wallet.
- `mascot-light.gif` / `mascot-dark.gif` — Generated email media.

## Execution policy

Only these two operator entry points are executable:

- `scripts/deploy-backend-hotfix.sh`
- `scripts/deploy-backend-db-migrations.sh`

Files in `scripts/internal/`, `scripts/migrations/`, and `scripts/tools/` are
non-executable helpers. The operator scripts call required helpers through
Bash or Node.js.

Internal OP2 builders require explicit temporary source and output paths. The
old `production/frontend/` mirror is not a deployment input and should not be
kept in the active project tree.
# Analytics migration

`migrate-business-analytics.mjs` installs anonymous session, journey-event,
daily aggregate, and verified payment-attribution fields. It is invoked only by
`deploy-backend-db-migrations.sh`; do not run the helper directly.

## Full verification cache

The full backend verifier is:

    ../tools/verify-server.sh

Normal runs skip unchanged heavy asset groups.
Use this when you intentionally want every backend asset URL re-requested:

    ../tools/verify-server.sh --fresh