Application Shell & Status Architecture

Canonical persistent application shell featuring user menu (UX-SHELL-01), environment badge (VER-UI-07), version status chip with health popover (UX-SHELL-04, VER-UI-06..09), 3-state theme toggle (UX-BRAND-08g), and user release history (VER-LOG-03).

Complex 9 Critical Rules Demonstrated

Critical Rules Demonstrated

Interactive Live Demonstration

Simulate Environment: Health State:

Platform Hub

PROD

Welcome to the App Shell Reference

This demo models the standard Alterspective application header. Click the User Menu or the Version Status Chip above to see how runtime state, build information, and account controls are kept clear and accessible.

Governing Architecture Rules

UX-SHELL-01 MUST

Account Actions in User Menu

In persistent app shells, account actions such as Sign Out, user profile, and preferences MUST live inside a user menu rather than as a freestanding shell action.

UX-SHELL-02 MUST

Status Cluster Kept Separate

Persistent app shells that expose runtime status MUST keep account actions separate from the status cluster. The Environment badge and Version status trigger form a dedicated utility group.

UX-SHELL-04 MUST

Deployment Timestamp & Build Metadata

The closed chip displays the running version (v1.4.2). The expanded status panel surfaces how long ago the version was published using a moment-style relative timestamp (e.g. Published 2 hours ago) along with the localized deployment timestamp sourced from /health (version.buildTime), never hardcoded.

VER-UI-07 MUST

Canonical Environment Labels

Visible environment badges MUST normalize runtime environment names to: DEV, TEST, PRE PROD, or PROD.

VER-UI-08 & 09 MUST

Dependency Health & Severity

Activating the version control surfaces dependency health. The chip severity reflects the highest unresolved impact (Healthy, Degraded, or Critical) with color AND text/icon cues.

VER-LOG-03 MUST

User-Reachable Release History

Every product MUST provide an accessible changelog or release history surface reachable directly from the version control (e.g. /changelog or What's New modal).

UX-BRAND-08g MUST

Accessible Runtime Theme Toggle

Every interactive surface MUST provide a 3-state runtime theme toggle (Light / Dark / System) in persistent chrome or user menu, persisted across sessions.

Reference Implementation (React / TypeScript)

import React, { useState, useEffect, useRef } from 'react';

export interface AppShellProps {
  appName: string;
  user: { name: string; email: string; avatarUrl?: string };
  versionInfo: {
    version: string;        // e.g. "1.4.2"
    sha: string;            // e.g. "a1b2c3d"
    buildDate: string;      // ISO 8601 UTC timestamp
    environment: 'DEV' | 'TEST' | 'PRE PROD' | 'PROD';
  };
  dependencies?: Array<{ name: string; status: 'healthy' | 'degraded' | 'critical' }>;
  onSignOut: () => void;
  children: React.ReactNode;
}

export function AppShell({ appName, user, versionInfo, dependencies = [], onSignOut, children }: AppShellProps) {
  const [userMenuOpen, setUserMenuOpen] = useState(false);
  const [statusOpen, setStatusOpen] = useState(false);
  const [changelogOpen, setChangelogOpen] = useState(false);

  return (
    <div className="app-shell-root">
      <header className="app-shell-header">
        
        <div className="shell-left">
          <img src="/logos/Alterspective_Logo_FA.png" alt="Alterspective" className="logo" />
          <span className="product-title">{appName}</span>
        </div>

        
        <div className="shell-right">
          
          <div className="user-menu-wrapper">
            <button onClick={() => setUserMenuOpen(!userMenuOpen)} aria-expanded={userMenuOpen}>
              <span className="avatar">{user.name.charAt(0)}</span>
              <span>{user.name}</span>
            </button>
            {userMenuOpen && (
              <div className="user-dropdown" role="menu">
                <div className="user-info">{user.email}</div>
                
                <ThemeToggle />
                <button onClick={onSignOut} className="signout-btn">Sign Out</button>
              </div>
            )}
          </div>

          
          <div className="status-cluster">
            <span className=env-badge env-$&#123;versionInfo.environment.toLowerCase().replace(' ', '-')&#125;>
              {versionInfo.environment}
            </span>

            <button
              onClick={() => setStatusOpen(!statusOpen)}
              className="version-chip"
              aria-label="System status & version"
            >
              <span className="health-dot" />
              <span>v{versionInfo.version}</span>
            </button>

            {statusOpen && (
                
                <div className="panel-timestamp">
                  Published <strong>{formatTimeAgo(versionInfo.buildDate)}</strong> ({new Date(versionInfo.buildDate).toLocaleString()})
                </div>
                <div>Commit: {versionInfo.sha}</div>
                
                <button onClick={() => { setStatusOpen(false); setChangelogOpen(true); }}>
                  What's New in this release
                </button>
              </div>
            )}
          </div>
        </div>
      </header>

      <main>{children}</main>
      {changelogOpen && <ChangelogModal onClose={() => setChangelogOpen(false)} />}
    </div>
  );
}