Engine Isolation — Operator Guide

Audience: Platform admin, MSP operator, on-call engineer
Availability: Public (monitoring endpoints), Admin (health-check UI)

What this means

PackMyApp is split into independent engines (Updates, Intune, Catalog, Auth, Forge, etc.). If one engine fails at startup or runtime, the rest of the site should remain available.

Quick checks

1. Overall health

GET /health

Look for:

status: ok or degraded
startup.degraded: true when database seed/init failed but the app still started
startup.errors: list of startup failure messages
email_delivery.status: email queue health

2. Per-engine snapshot

GET /health/engines

Response includes:

summary.enabled / summary.disabled
engines.<name>.status: enabled or disabled
engines.<name>.detail: import/runtime disable reason (when disabled)

3. Admin health-check UI

Open /admin/health-check after admin sign-in for deep capability probes per subsystem.

When an engine is disabled

Symptom	Likely cause	Action
HTTP 503 with `{ "engine": "updates" }`	Updates module failed import or was marked disabled	Check app logs for `Engine 'updates' disabled`; fix import error; redeploy
Catalog works, Updates menu empty	Updates engine disabled at startup	`GET /health/engines` → inspect `updates`
Entire API returns 503 on auth DB errors	Database unreachable during session check	Restore DB connectivity; check `startup.database`
`status: degraded` on `/health`	DB seed/init failed	Inspect `startup.errors`; fix SQLite path/permissions

Release gate

Before deploy, run:

python3 tools/release_gate.py

This validates:

Engine-isolation wiring in app/api/router.py
Dependency boundaries for routes
Provider registry integrity
Critical pytest suite (includes tests/test_engine_isolation.py)

Local test dependencies

pip install -r requirements-dev.txt
pytest