# 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.