jinojose/aipackage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ebaa2e7219
aipackage/specs/001-enterprise-experience/plan.md

8.8 KiB
Raw Blame History

Implementation Plan: Enterprise Appliance Experience Hardening

Branch: 001-enterprise-experience | Date: 2026-07-12 | Spec: spec.md

Input: Feature specification from specs/001-enterprise-experience/spec.md

Summary

Harden Nexus One AI through three independently accepted phases: setup/readiness, daily administration, and recovery/support. Preserve the current static portal, FastAPI management API, SQLite appliance data, shell/Ansible installer, and license compatibility model. Introduce shared experience contracts for truthful states, durable operations, redacted support evidence, consistent entitlements, accessibility, and release provenance rather than replacing the product architecture.

Technical Context

Language/Version: Python 3.11; browser-native HTML/CSS/JavaScript; Bash; Ansible YAML

Primary Dependencies: FastAPI 0.111+, Uvicorn 0.29+, python-jose, passlib/bcrypt, psutil, APScheduler, Nginx, systemd, Ansible, Ubuntu autoinstall

Storage: SQLite at /opt/cezen/data/cezen.db; JSON appliance records under /opt/cezen; filesystem backups under /opt/cezen/backups; systemd journal and install logs

Testing: Python unit/contract tests to be added around backend state and redaction; browser journey and accessibility checks; shell/static validation; Ansible syntax checks; clean-install, upgrade, interruption, backup/restore, pilot, and packaged-artifact verification

Target Platform: Nexus One AI Workstation and Server appliances on Ubuntu 22.04, accessed through supported desktop browsers on customer-controlled networks

Project Type: On-premises appliance package containing a static web portal, management API, installer, deployment automation, system services, and ISO build paths

Performance Goals: Readiness visible within 10 seconds of portal entry under normal appliance conditions; local navigation feedback within 1 second; operation acknowledgement within 2 seconds; progress freshness appropriate to the underlying operation and never presented as live when stale

Constraints: Restricted/offline operation after installation; existing starter/basic/pro/max compatibility identifiers; Workstation remains outside the Server tier ladder; no fabricated runtime state; secrets excluded from diagnostics; WCAG 2.2 AA; safe migration of existing SQLite appliances; no unsupported HA or recovery claims

Scale/Scope: Approximately 60 static portal pages, one large FastAPI service, two first-boot interfaces, four Server tiers plus Workstation packaging, multiple Ansible roles, and three ISO build paths. Phase 1 is limited to setup/readiness on one representative Workstation and one representative Server configuration.

Constitution Check

GATE: Passed before Phase 0 and re-checked after Phase 1 design.

  • Enterprise experience — PASS: The spec and UI contract define primary, loading, empty, ready, degraded, failed, restricted, stale, and recovery states with consistent terminology.
  • Lifecycle safety — PASS: Operation state is durable; setup, interruption, backup/restore, upgrade, retry, resume, rollback, and escalation responsibilities are explicitly mapped.
  • Security and audit — PASS: Existing server-side authorization is preserved; new audit and support-evidence contracts require redaction, actor, scope, result, and correlation identifiers.
  • Entitlement and packaging — PASS: The plan preserves internal identifiers, keeps Workstation separate, and requires portal/API/installer/Ansible/documentation/ISO consistency evidence.
  • Evidence — PASS: Quickstart validation distinguishes static, local, deployed, live-appliance, pilot, and release-artifact evidence.

Post-design re-check: PASS. No constitutional exception is required.

Phased Design

Phase 1 — Setup and Readiness

  1. Establish canonical customer-facing state, severity, entitlement, operation, and error vocabulary.
  2. Make browser and console setup persist non-secret progress and expose safe resume/retry behaviour.
  3. Replace process-local install status as the sole truth with a durable operation record.
  4. Normalize readiness into a customer-impact view with freshness and actionable next steps.
  5. Align Workstation and representative Server setup/readiness behaviour.
  6. Validate WCAG 2.2 AA, clean install, interruption, restricted-network guidance, and artifact provenance before pilot.

Phase 2 — Daily Administration

  1. Introduce shared portal presentation helpers for status, errors, operations, entitlement, and accessible announcements while retaining static delivery.
  2. Apply the common shell and state contract first to dashboard, appliance, health, licensing, users/security, models, and knowledge journeys.
  3. Remove fabricated production examples or label them explicitly as samples.
  4. Provide a unified operations history for consequential and long-running actions.
  5. Add role-aware orientation and locally available contextual guidance.
  6. Complete the daily-administration portions of entitlement consistency and guided handover.

Phase 3 — Recovery and Support

  1. Model backup, restore, restart, upgrade, removal, diagnostic export, and escalation as authorized, durable operations.
  2. Add redacted support-evidence generation and correlation across API, audit, install, and service state.
  3. Define recovery preconditions, customer impact, confirmation, progress, outcome, and next action.
  4. Validate upgrade/interruption/rollback paths and controlled pilot results before general release.

Entitlement consistency is a cross-cutting workstream spanning all three delivery phases. Guided handover is accepted within Delivery Phase 2. These workstreams do not create additional delivery phases or alter the approved order.

Project Structure

Documentation (this feature)

specs/001-enterprise-experience/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── customer-experience-contract.md
└── checklists/
    └── requirements.md

Source Code (repository root)

autoinstall/
├── websetup/server.py          # browser setup and current process-local install state
├── firstboot-setup.sh         # console setup flow
├── user-data*                # ISO-specific first-boot entrypoints
└── build-iso*.sh             # Workstation/Server ISO build paths

cezen-portal/
├── branding.js               # shared branding/entitlement behaviour
├── auth.js                   # session and role enforcement
├── style.css                 # shared design/accessibility primitives
├── index.html                # primary landing experience
├── appliance.html            # readiness, license, audit, backup/restore
├── health.html               # subsystem health experience
└── *.html                    # remaining administration and user journeys

ansible/roles/cezen-backend/
├── files/main.py             # API, SQLite model, audit, readiness, backups
├── files/cezen_license.py    # deployed entitlement helper
├── files/cezen-api.service   # runtime contract
└── tasks/main.yml            # backend deployment

ansible/roles/cezen-nginx/          # static portal deployment and routing
scripts/cezen_license.py            # canonical source entitlement helper
scripts/cezen-backup.sh             # appliance backup/restore utility
install.sh                          # phase orchestration and install record
ansible/{starter,entry,pro,max}.yml # Server deployment profiles

Structure Decision: Extend the existing appliance package in place. Keep the static portal and single management service for this initiative; extract shared modules only where needed to enforce one state/operation contract. Treat scripts/cezen_license.py as the canonical entitlement source and keep deployed copies synchronized through explicit verification.

Migration and Compatibility Strategy

  • Additive SQLite changes MUST use idempotent migrations executed before new reads/writes; startup CREATE TABLE IF NOT EXISTS alone is insufficient for column evolution.
  • Existing endpoints remain compatible during each phase. New envelope fields are additive until all packaged portal consumers migrate.
  • Existing install and license JSON fields remain readable. New operation/progress data is separate and excludes raw signed license payloads.
  • Existing backups remain restorable; schema version and compatibility are checked before mutation.
  • Removal preserves backups by default, explicitly inventories retained/deleted data, and records the limits of rollback before confirmation.
  • Portal, API, installer, canonical/deployed license helpers, Ansible roles, docs, and ISO contents are compared during release validation.

Complexity Tracking

No constitutional violations require justification.