ARCHITECTURE

/**
 * 6D Dashboard - Comprehensive System Summary
 * All components, types, configuration, and integration patterns
 */

// ============================================================================ // COMPONENT ARCHITECTURE OVERVIEW // ============================================================================

/**

• The 6D Dashboard is organized into three main layers:
• 1. PRESENTATION LAYER (components/)
• ├─ LCARS Frame: Grid-based layout container
• ├─ 3D Scene: react-three-fiber with SixDWedge instances
• ├─ HUD Panels: HealthHeader, DisciplinePanel, StatusChip, KpiMiniCard
• └─ GridHeim Sheets: OKRs, Budget, Projections, Plan, SWOT, Risks
• 2. STATE MANAGEMENT (data/)
• ├─ sixd.types.ts: TypeScript type definitions (DisciplineState, HealthScore, Kpi, etc.)
• ├─ sixd.config.ts: Configuration (labels, colors, scoring weights)
• ├─ sixd.state.ts: Redux slice with reducers for data & UI state
• ├─ sixd.selectors.ts: Derived state & complex computations
• ├─ sixd.mappers.ts: Convert THOR responses to 6D types
• └─ *test files: Jest unit tests for selectors & scoring
• 3. SERVICES LAYER (services/)
• └─ thor.client.ts: THOR API client wrapper (mock for dev, real API for prod) */

// ============================================================================ // DATA TYPES & CONTRACTS // ============================================================================

/**

• DisciplineKey (union type)
• One of six disciplines in the framework:
• 'decide' | 'set_goals' | 'align_systems' | 'work_plan' | 'innovate' | 'step_back' */

/**

• HealthStatus (union type)
• Four primary statuses + paused:
• 'healthy' | 'watch' | 'risk' | 'critical' | 'paused'
• Status transitions use hysteresis to prevent flicker:
• • Healthy: score 65-100 (move to Watch if < 40)
• • Watch: score 40-70 (move to Healthy if > 75, or Risk if < 20)
• • Risk: score 20-45 (move to Watch if > 50, or Critical if < 0)
• • Critical: score 0-25 (move to Risk if > 30) */

/**

• HealthScore (interface)
• Overall organizational health snapshot:
• • overall: 0..100 numeric score
• • trend7d / trend30d: delta in points (e.g., +2.5 or -1.2)
• • status: derived health status with hysteresis
• • nextMilestone?: human-readable goal (e.g., "Achieve 85 health by Q1")
• • updatedAt: ISO timestamp */

/**

• DisciplineState (interface)
• Full state of a single discipline:
• • key: DisciplineKey (immutable)
• • label: display name (e.g., "Decide What's Important")
• • status: current HealthStatus
• • score: 0..100 numeric health
• • kpis: array of KPI objects with current/target/trend
• • starts / stops: StartStopItem arrays (actionable items for this discipline)
• • blockerCount: integer count of items with status='blocked'
• • lastReview?: ISO date of last cycle review */

/**

• Kpi (interface)
• Key Performance Indicator bound to a discipline:
• • id, name: identifiers
• • discipline: DisciplineKey (which discipline this KPI measures)
• • target, current: numeric values
• • unit: 'count' | 'usd' | 'ms' | 'pct' | 'custom'
• • trend?: +/- delta since last period
• • status: derived HealthStatus (based on attainment) */

/**

• StartStopItem (interface)
• Discrete action item within a discipline:
• • id, title: identifiers
• • discipline: DisciplineKey
• • type: 'start' (begin) | 'stop' (cease)
• • status: 'todo' | 'doing' | 'done' | 'blocked'
• • ownerId, ownerName: THOR user reference
• • dueDate, notes: optional metadata */

/**

• SixDOverview (interface)
• Complete 6D state snapshot (fetched from THOR):
• • health: HealthScore
• • disciplines: Record<DisciplineKey, DisciplineState> (all 6 disciplines)
• • organizationId: optional org ID
• • cycleStartDate / cycleEndDate: 90-day cycle bounds
• • updatedAt: ISO timestamp */

// ============================================================================ // REDUX STATE SHAPE // ============================================================================

/**

• SixDState (Redux slice)

  {
    overview: SixDOverview | null,
    loading: boolean,
    error: string | null,
    focus: DisciplineKey | null,
    selectedSheet: 'budget' | 'projections' | 'okrs' | 'plan' | 'swot' | 'risks' | null,
    lastRefresh: ISO timestamp | null,
    missionResults: [{ id, title, progress, delta }],
  }

• Actions:

  • setOverview(SixDOverview)
  • setLoading(boolean)
  • setError(string | null)
  • setFocus(DisciplineKey | null)
  • setSelectedSheet(...)
  • updateDisciplineScore({ discipline, score })
  • updateDisciplineStatus({ discipline, status })
  • addStartStopItem({ discipline, item })
  • updateStartStopItem({ discipline, itemId, updates })
  • removeStartStopItem({ discipline, itemId })
  • setMissionResults([...]) */

// ============================================================================ // SCORING ALGORITHM (Selector Logic) // ============================================================================

/**

• computeDisciplineScore(discipline, weights)
• Derives a health score for a discipline using weighted components:
• score = (
• KR_attainment * 0.6 +
• plan_throughput * 0.2 +
• variance_stability * 0.1 +
• risk_posture * 0.1
• ) * 100
• Then applies hysteresis to map to HealthStatus:
• • If status='healthy' & score>75, stay healthy (no downgrade unless < 40)
• • If status='watch' & score>75, upgrade to healthy
• • If status='watch' & score<20, downgrade to risk
• • etc.
• Hysteresis prevents flickering on boundary conditions. */

/**

• computeOverallHealth(disciplines[])
• Averages discipline scores to produce SixDOverview.health:
• • overall: mean of all discipline.score
• • trend7d / trend30d: derived from historical snapshots
• • status: hysteresis-adjusted HealthStatus for the avg score */

// ============================================================================ // 3D SCENE (react-three-fiber + THREE.js) // ============================================================================

/**

• SixDScene Component
• Canvas with:
• • OrbitControls (default orthographic, tweens to perspective on focus)
• • SixDWedge x6 (one per discipline)
• • HealthCenterOrb (displays overall score)
• • Lighting (ambient + two point lights)
• • EffectComposer with Bloom (disabled on prefers-reduced-motion)
• Props:
• • disciplines: DisciplineState[]
• • focused: DisciplineKey | null
• • onFocusChange: (key) => void
• Interactivity:
• • Hover wedge: lifts (+0.08 y), shows tooltip
• • Click wedge: calls onFocus, triggers camera tween
• • Arrow ←/→: cycle through wedges
• • Enter: focus hovered wedge
• • Esc: reset focus */

/**

• SixDWedge Component
• Single extruded wedge at ring position:
• • Geometry: ExtrudeGeometry (60° wedge, depth 0.4, beveled)
• • Material: MeshPhysicalMaterial with emissive bound to score
• • Emissive color: getStatusColor(discipline.status)
• • Emissive intensity: 0.3 + (score/100)*0.7
• • Pulse: sine wave modulates intensity on beat
• Props:
• • discipline: DisciplineState
• • index: 0..5
• • focused, hovered: booleans
• • callbacks: onHover, onUnhover, onFocus */

/**

• HealthCenterOrb
• Central icosahedron displaying overall health:
• • Rotates subtly every frame
• • Emissive color & intensity reflect overall health status/score
• • Html overlay shows numeric score + "Health" label */

// ============================================================================ // LCARS LAYOUT // ============================================================================

/**

• LcarsFrame Component
• Grid-based container:
• grid-template-areas: "header header" / "sidebar content" / "footer footer"
• grid-template-columns: 4rem 1fr
• grid-template-rows: 6rem 1fr 8rem
• Props:
• • header: ReactNode (HealthHeader with score + trends)
• • leftRailProps: { focus, onSelect } (discipline filter buttons)
• • children: ReactNode (main content, typically SixDScene)
• • bottomCap: ReactNode (sheet tabs + tables)
• Styling:
• • Colors from --aurora-* CSS variables
• • Borders with --aurora-border-med
• • Rounded corners on header/footer (LCARS aesthetic) */

/**

• LcarsRail & LcarsPill Components
• Reusable button/pill UI elements:
• • LcarsPill: pill-shaped button with hover/active states
• • Props: label, onClick, active, variant, size */

// ============================================================================ // HUD PANELS // ============================================================================

/**

• HealthHeader
• Top-left section showing:
• • Overall score (large number, e.g., "78")
• • 7-day trend (e.g., "↗ +2.5pt")
• • 30-day trend (e.g., "↘ -1.2pt")
• • Next milestone (right-aligned)
• Props: health: HealthScore | null, loading, error */

/**

• StatusChip
• Compact inline status indicator:
• • Colored dot + label
• • E.g., "● watch" in amber
• Props: status: HealthStatus, label?: string */

/**

• DisciplinePanel
• Right-side panel (when discipline is focused):
• • Header with SIXD_HEADERS[key] + StatusChip
• • Description (SIXD_PARAGRAPHS[key])
• • Health score bar
• • Expandable KPIs section (grid of KpiMiniCard)
• • Expandable Start/Stop section (StartStopCard x N)
• • Sheet buttons (OKRs, Plan, Budget, Risks deep links)
• Props: discipline: DisciplineState | null, onSheetSelect?: (sheetType) => void */

/**

• KpiMiniCard
• Compact KPI display within DisciplinePanel:
• • Name + trend indicator
• • Progress bar (current / target) */

/**

• StartStopCard
• Display of a StartStopItem:
• • Type indicator (+ Start / - Stop)
• • Title
• • Owner name (if set)
• • Status badge (todo/doing/done/blocked) */

// ============================================================================ // GRIDHEIM SHEETS // ============================================================================

/**

• GridHeimSheet Component
• Generic table wrapper for editable sheets:
• • Props: sheetId, title, columns, data, onDataChange, onCellEdit
• • Click cell to edit (inline text input)
• • Press Enter or blur to save
• • Calls onCellEdit callback on change
• Specific sheet components:
• • OkrsSheet: objective_id, objective, discipline, key_result, target, current, owner
• • BudgetSheet: account, qtr, plan_usd, actual_usd, variance_usd (formula), notes
• • ProjectionsSheet: metric, t0, t30, t60, t90, assumption
• • PlanSheet: work_id, task, objective_id, assignee, wip_state, eta, blocker
• • SwotSheet: type(S/W/O/T), statement, evidence, linked_objectives
• • RisksSheet: risk_id, summary, likelihood(1-5), impact(1-5), mitigation, owner, status */

// ============================================================================ // THEME & TOKENS // ============================================================================

/**

• auroraTokens (CSS variables)
• Color palette:
• --aurora-bg-0: #0a0f14 (deep black)
• --aurora-fg-0: #e6f6ff (bright cyan text)
• --aurora-accent-1: #52d1ff (primary cyan interactive)
• --aurora-accent-2: #b782ff (purple secondary)
• --aurora-ok: #00d98b (green / healthy)
• --aurora-warn: #ffb020 (amber / watch)
• --aurora-danger: #ff5470 (red / critical)
• • surfaces, borders, shadows, gradients, etc.
• Spacing (rem-based):
• --spacing-xs: 0.25rem, --spacing-sm: 0.5rem, ..., --spacing-3xl: 4rem
• Typography:
• --font-sans: system fonts, --font-mono: Fira Code
• --font-size-xs through --font-size-4xl
• Transitions:
• --transition-fast: 150ms, --transition-normal: 250ms, --transition-slow: 350ms */

/**

• STATUS_COLOR_MAP
• Maps HealthStatus → CSS color:
• healthy → var(--aurora-ok)
• watch → var(--aurora-warn)
• risk → #ff7a59
• critical → var(--aurora-danger)
• paused → #6b7280 */

// ============================================================================ // INSTRUMENTATION & OBSERVABILITY // ============================================================================

/**

• window.vlk.instrument(event, data)
• Hook for observability events:
• • sixd.disciplineSelected: { discipline, timestamp }
• • sixd.sheetOpened: { sheet, timestamp }
• • sixd.startStopUpdated: { itemId, status, timestamp }
• • sixd.kpiEdited: { kpiId, newValue, timestamp }
• Integration:
• In production, wire to Segment, Mixpanel, etc. for analytics. */

// ============================================================================ // THOR INTEGRATION // ============================================================================

/**

• ThorSixDClient (mock implementation)
• Methods:
• • getHealth(organizationId?): Promise<HealthScore>
• • getDisciplines(organizationId?): Promise<Record<DisciplineKey, DisciplineState>>
• • getOverview(organizationId?): Promise<SixDOverview>
• • updateStartStop(orgId, disciplineKey, itemId, updates): Promise<StartStopItem>
• • createStartStop(orgId, disciplineKey, item): Promise<StartStopItem>
• • updateKpi(orgId, kpiId, updates): Promise<Kpi>
• In production, replace with @thorapi/redux generated services:
• • useGetGoalsQuery()
• • useGetTasksQuery()
• • useMutateGoalMutation()
• • etc. */

/**

• mappers.ts functions:
• • mapThorWorkflowToSixD(thorData): SixDOverview
• • mapGoalToKpi(goal, discipline): Kpi
• • mapTaskToStartStop(task, discipline): StartStopItem
• • computeDisciplineFromThor(key, goals[], tasks[]): Partial<DisciplineState> */

// ============================================================================ // TESTING STRATEGY // ============================================================================

/**

• Unit Tests (Jest, src/data/*.test.ts)
• • computeKrAttainment(kpis): verify ratio calculations
• • computeStatusWithHysteresis(score, prevStatus): verify transitions, no flicker
• • Selectors: verify derived state correctness
• • Mappers: verify THOR → 6D conversion
• Target: ≥80% coverage for data layer */

/**

• E2E Tests (Playwright, src/tests/e2e/dashboard-6d.spec.ts)
• • Load dashboard, display health
• • Hover/click wedges, show tooltip/focus
• • Keyboard navigation (arrows, Enter, Esc)
• • Open sheets, edit cells
• • Accessibility audit (axe-core)
• • Performance metrics (FCP < 2s)
• Target: Lighthouse CI performance ≥90, a11y ≥95 */

// ============================================================================ // PERFORMANCE BUDGETS & OPTIMIZATIONS // ============================================================================

/**

• JS Bundle: < 230KB gzip (initial route)
• • Code splitting: react-three, redux-core separate chunks
• • Tree-shaking: unused THREE exports pruned
• • Minification: vite.build.terserOptions configured
• 3D Render: ≤8ms per frame on M1 (FPS ≥55)
• • Instanced geometry for wedges
• • Frozen transforms (no updates per frame unless focused)
• • Lazy postprocessing (Bloom disabled on prefers-reduced-motion)
• • LOD (level-of-detail) for complex meshes
• TTI: ≤2.0s on mid-tier hardware
• • Lazy-load GridHeim sheets (only active sheet renders)
• • Debounce THOR queries (300ms)
• • Memoize selectors (reselect)
• Accessibility Optimizations:
• • prefers-reduced-motion: disable animations, bloom
• • ARIA labels on all interactive elements
• • Keyboard shortcuts (arrow keys, Enter, Esc)
• • Screen reader announcements on status changes */

// ============================================================================ // DEVELOPMENT WORKFLOW // ============================================================================

/**

• Hot Module Reload (HMR)
• • Vite dev server watches src/** changes
• • Components reload instantly
• • State preserved across reloads
• Redux DevTools
• • Time-travel debugging
• • Action inspector
• • Can replay action sequences
• Environment Variables
• • .env.local: local overrides (not committed)
• • .env.example: template for developers
• • REACT_APP_THOR_API_URL, etc. */

// ============================================================================ // CONFIGURATION & CUSTOMIZATION // ============================================================================

/**

• sixd.config.ts
• All user-facing content can be customized:
• • SIXD_HEADERS: discipline names
• • SIXD_PARAGRAPHS: descriptive text
• • SIXD_TOOLTIPS: hover text
• • SIXD_SHORT_DESCRIPTIONS: brief summaries
• • STATUS_COLOR_MAP: color scheme
• • DEFAULT_SCORING_WEIGHTS: KR/plan/variance/risk ratios
• Call mergeSixDConfig(userConfig) to apply overrides at startup. */

// ============================================================================ // ERROR HANDLING & RESILIENCE // ============================================================================

/**

• THOR API Failures
• • Retry with exponential backoff (3x)
• • Show LCARS toast with retry button
• • Scene shows muted neutral color
• • SR announcement: "Unable to load health data"
• State Sync Issues
• • Idempotent mutations (update/create already have ID)
• • Optimistic UI updates (then reconcile with server)
• • Debounce rapid edits (300ms)
• 3D Scene Crashes
• • Try-catch around useFrame hook
• • Fallback to 2D health bar if WebGL unavailable
• • Log to console + observability */

// ============================================================================ // QUICK REFERENCE: KEY FILE LOCATIONS // ============================================================================

/**

• Type Definitions: src/data/sixd.types.ts
• Configuration: src/data/sixd.config.ts
• Redux State: src/data/sixd.state.ts
• Selectors & Scoring: src/data/sixd.selectors.ts
• THOR Mappers: src/data/sixd.mappers.ts
• Main Route: src/app/routes/dashboard-6d/index.tsx
• LCARS Layout: src/components/lcars/LcarsFrame.tsx
• 3D Scene: src/components/three/SixDScene.tsx
• HUD Panels: src/components/hud/HealthHeader.tsx, DisciplinePanel.tsx
• GridHeim Sheets: src/components/sheets/GridHeimSheets.tsx
• THOR Client: src/services/thor.client.ts
• Theme Tokens: src/theme/aurora-tokens.ts
• LCARS CSS: src/theme/lcars-layout.css.ts
• Tests (Unit): src/data/*.test.ts
• Tests (E2E): src/tests/e2e/dashboard-6d.spec.ts
• Setup: src/tests/setup.ts
• Entry Point: src/main.tsx
• Config (Vite): vite.config.ts
• Config (Jest): jest.config.cjs
• Config (Playwright): playwright.config.ts
• Config (TypeScript): tsconfig.json
• Manifest: package.json
• HTML Shell: index.html
• README: README.md */