5.1 KiB
Research: Enterprise Appliance Experience Hardening
Decision 1: Evolve the Existing Architecture
Decision: Retain the static portal, FastAPI management API, SQLite appliance store, shell/Ansible installer, Nginx, and systemd deployment model.
Rationale: The current architecture already exposes authentication, audit, readiness, entitlement, backup/restore, health, and installation flows. Enterprise quality depends first on consistent state, durability, recovery, and validation—not a framework rewrite that would expand risk.
Alternatives considered: Rebuild the portal as a single-page application; split the backend into services; adopt an external workflow engine. Deferred because none is required to satisfy Phase 1.
Decision 2: Use Durable Operations as the Cross-Surface Backbone
Decision: Represent installation and later consequential actions as durable operation records with lifecycle, progress, actor, scope, timestamps, result, recovery action, and correlation ID.
Rationale: Browser setup currently keeps install status in process memory, while the API runs multiple workers and appliance actions can outlive sessions or processes. A durable record provides one truth for refresh, restart, audit, diagnostics, and support.
Alternatives considered: Continue process-local status; infer progress exclusively from logs; add a separate message broker. Process-local status is not recoverable, logs are not a stable customer contract, and a broker is unnecessary for the current appliance scale.
Decision 3: Define One Customer-Facing State Vocabulary
Decision: Normalize state into loading, empty, ready, degraded, failed, restricted,
unavailable, and stale, with severity, freshness, impact, and next action.
Rationale: Existing pages use several incompatible labels and colour treatments. A shared contract prevents each page from inventing meaning and supports accessibility and acceptance tests.
Alternatives considered: Preserve page-specific vocabularies; expose raw service states. Both produce inconsistent customer meaning and leak implementation concepts.
Decision 4: Keep Entitlement Logic Canonical and Additive
Decision: Preserve Workstation separation and Server compatibility identifiers. Treat
scripts/cezen_license.py as canonical and verify parity with installer/backend deployed copies.
Rationale: The repository already documents the separation and copies license helpers into more than one runtime location. Replacing identifiers would create avoidable upgrade and license risk.
Alternatives considered: Rename internal tiers; merge Workstation into the Server ladder; allow each surface to derive its own mapping. Rejected for compatibility and drift risk.
Decision 5: Introduce Explicit SQLite Schema Evolution
Decision: Use versioned, idempotent database migrations for new operation/support-evidence fields and tables, with pre-change backup and compatibility checks.
Rationale: The backend creates many tables directly during startup. New enterprise lifecycle data must be safely introduced on existing customer appliances and included in backup/restore validation.
Alternatives considered: Add only new tables through startup creation; replace SQLite; reset data on upgrade. Startup creation lacks controlled evolution, replacement is disproportionate, and reset is unacceptable for customer appliances.
Decision 6: Shared Portal Primitives Without Immediate Framework Migration
Decision: Add shared browser-native helpers and CSS primitives for states, operations, errors, focus, announcements, confirmation, and entitlement rather than rewriting all pages at once.
Rationale: The portal is a large static HTML/JavaScript surface already deployed by file sync. Shared primitives enable phased adoption and reduce visual/behavioural drift with minimal packaging change.
Alternatives considered: Full portal rewrite; page-by-page independent cleanup. A rewrite conflicts with phased risk reduction; independent cleanup preserves inconsistency.
Decision 7: WCAG 2.2 AA Requires Automated and Manual Evidence
Decision: Combine automated checks with manual keyboard, focus, status-announcement, zoom/reflow, and representative assistive-technology journeys.
Rationale: Automated checks cannot prove complete accessibility, especially for dynamic status, error recovery, and consequential operations.
Alternatives considered: Automated checks only; informal review; AAA. The first two are insufficient for formal AA acceptance; AAA exceeds the approved scope.
Decision 8: Release Through Evidence Gates
Decision: Require internal evidence, controlled pilot evidence, joint product and delivery/support approval, then general release; validate both source revision and packaged artifact identity.
Rationale: Installation and recovery changes need customer-like appliance evidence, while the repository contains multiple source and ISO delivery surfaces that can diverge.
Alternatives considered: Direct general release after local tests; UI-only acceptance; checksum without journey validation. Each leaves a material enterprise-appliance risk untested.