Control Room Architecture¶

Architectural Principles¶

graph TD
    A["User Interactions (Ribbon / Explorer / Viewport / Inspector)"] --> B["Module Kernel & Registry"]
    B --> C["Zustand State Stores & Draft Isolation"]
    C --> D["OpenAPI v2 Client & SSE/WS Event Pipeline"]
    D --> E["FullMag Rust/C++ Backend Session Engine"]
    E --> F["Canonical ProblemIR Lowering & Validation"]
    F --> G["FDM & FEM CPU/GPU Solvers"]
    G --> H["Binary Vector Buffers & Realtime Metrics"]
    H --> I["Three.js / WebGL 3D Viewport & ECharts"]

1. Physical-Model Alignment: The UI operates on micromagnetic domain concepts (geometry, materials, physical interactions, discretization, and stages) rather than exposing numerical storage details.

2. Modular Kernel Architecture: Feature areas are self-contained modules (src/modules/*) registered dynamically with the core shell.

3. Explicit Draft Isolation: Inspector property edits remain in an isolated draft state until committed by the user, preventing partial or corrupt configuration frames from reaching the active solver session.

4. SSR Hydration Consistency: Client components reading runtime state use useSyncExternalStore or hydration gates so the first client render matches the server-rendered state.

5. Token-First Design System: Styling is governed by central --fm-* CSS tokens (Catppuccin Mocha for dark mode, Latte for light mode), Tailwind CSS, and shadcn/ui shared primitives.

Module Kernel & Layout Slots¶

The Control Room shell layout is partitioned into flexible Layout Slots managed by src/kernel/modules:

apps/control-room/src/
├── kernel/              # Core shell runtime, layout manager, API client, event bus
│   ├── api/             # OpenAPI v2 client, generated types, binary codecs
│   ├── modules/         # Module registry, manifest resolver, slot contracts
│   └── state/           # Central session stores, selection, layout persistence
└── modules/             # Self-contained UI feature modules
    ├── ribbon/          # Header strip tabs & command groups
    ├── explorer/        # Semantic tree model browser
    ├── viewport-3d/     # WebGL canvas, Three.js scene, vector field shaders
    ├── inspector/       # Property panel, draft editor, unit converters
    ├── live-charts/     # ECharts time-series & energy component graphs
    ├── status-bar/      # Session state, solver engine, device metrics
    └── app-menu/        # Command palette (Ctrl+K) & workspace settings

export const inspectorModuleManifest: ModuleManifest = {
  id: "inspector",
  name: "Inspector Panel",
  slots: [
    {
      slotId: "shell.right",
      component: InspectorShell,
      priority: 10,
    },
  ],
  commands: [
    {
      id: "inspector.apply-draft",
      label: "Apply Draft Changes",
      shortcut: "Ctrl+Enter",
    },
  ],
};

Viewport 3D & WebGL Lifecycle¶

The 3D Viewport (src/modules/viewport-3d) renders geometric domains and 3D vector fields (\(\mathbf{m}, \mathbf{H}_{\text{eff}}\)) using Three.js and React Three Fiber (R3F).

State Management & Invalidation Pipeline¶

Workspace state is maintained across three distinct tiers:

1. Selection & Layout Store: Tracks selected tree node IDs, panel visibility, ribbon tab index, and visual profile settings.

2. Draft Property Store: Holds transient uncommitted user edits in the Inspector before explicit application.

3. Session & Runtime Store: Synchronizes with the active backend session (/v2/sessions/current/*), listening to real-time SSE event channels for stage completions, metric updates, and field invalidations.

User Input ──> Draft Store ──(Apply Draft)──> Session API ──> SSE Event ──> Viewport Invalidated ──> GPU Redraw

Technical Specifications¶

Control Room crosswalk¶

This architecture page has no direct authoring screen. Use the object, material, physics, mesh, or stage editor named by the relevant terminal API page; architecture concepts are currently inspection-only unless a concrete UI owner is listed. TODO: frontend support applies to architecture capabilities without a corresponding control. See Control Room capability register.

Python/API crosswalk¶

This page documents architecture rather than a standalone Python callable. Exact constructors, arguments, validation, and examples belong to the linked Python API pages; do not infer a public function from an internal architecture term.

Physics and bibliography scope¶

No independent physical model is introduced here. Scientific equations are owned by the applicable physics or numerical-methods page. Bibliography: not applicable to this architecture overview; implementation ownership is recorded in the source-code references on the terminal page.

Source-code index¶

• No standalone Python callable is introduced by this architecture page. Use the exact source symbol named by the linked API or implementation page; architecture terms alone are not public functions.