95 lines
5.1 KiB
Markdown
95 lines
5.1 KiB
Markdown
# 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.
|