Control Room Architecture¶
Last changes: Documentation changelog
The FullMag Control Room (apps/control-room) is built as a modular, resource-first web application designed for interactive micromagnetic problem authoring, high-throughput WebGL visualization, and live runtime observation.
It bridges browser interaction with FullMag’s underlying Rust/C++ solvers and fullmag.live
Python sessions through OpenAPI v2 JSON control-plane contracts, canonical ProblemIR
lowering, HTTP binary data-plane codecs, and WebSocket invalidation events.
Architectural Principles¶
User Interactions / Live Python (`fm.connect`)
──> Authoring Transaction (`scene_revision` fenced) or Control Command
──> OpenAPI v2 Session API & Canonical ProblemIR Lowering
──> WebSocket Revision Invalidation ──> Scoped Resource Cache Invalidation
──> HTTP Binary Data Plane (`FMVP` / `FMMT` / `FMRM` / `FMCS` / `FMTB` / `FMMQ`)
──> Three.js R3F 3D Viewport, 2D Field Map & ECharts Plots
Physical-Model Alignment: The UI operates on micromagnetic domain concepts (
object_id, regions, materials, physical interactions, discretization, and stages) rather than mixing UI display names with solver behavior.Modular Kernel Architecture: Feature areas are self-contained modules (
src/modules/*) registered dynamically into kernel layout slots (src/kernel/module).Explicit Draft Isolation & Conflict Fencing: Inspector property edits stay in isolated draft stores (
"staged","liveViewport", or"immediate") until committed withscene_revisionpreconditions so neither partial drafts nor concurrent Python writes overwrite state silently.SSR Hydration Consistency: Client components reading runtime, tab-route, or theme stores use
useSyncExternalStoreor hydration gates so the first client render matches server-rendered HTML.Token-First Design System: Central
--fm-*CSS custom properties (theme.css) implement Catppuccin Mocha (data-theme="dark") and Catppuccin Latte (data-theme="light"), paired with Tailwind utilities and shadcn/Radix shared primitives.
Shell Routing, Module Kernel & Layout Slots¶
Browser URL routing (src/kernel/layout/tabRoutes.ts, InstanceTabStrip.tsx) supports /home
(non-blocking Start Screen overlay preserving mounted sessions), /session/<slug>,
/session/<slug>?port=<port>, and /instance/<port> for switching seamlessly across parallel
local instances or Docker Compose development groups.
The Control Room shell layout partitions responsibilities across kernel/ and modules/:
apps/control-room/src/
├── kernel/ # Core shell runtime, layout, API client, event bus, codecs
│ ├── api/ # OpenAPI v2 client, generated types, binary codecs (FMVP/FMMT/FMRM/FMCS/FMTB/FMMQ...)
│ ├── authoring/ # History mutations, quantity fields, draft guards
│ ├── commands/ # CommandRegistry, shortcuts, diagnostics, workspace policy
│ ├── layout/ # InstanceTabStrip, tabRoutes, AppMenuBar, layout persistence
│ ├── module/ # Module registry, manifest resolver, slot contracts
│ ├── realtime/ # WebSocket RealtimeClient & RealtimeInvalidationBridge
│ ├── resources/ # Revision-aware resource hooks, cache scoping, invalidation
│ └── selection/ # Unified selection controller across tree, 3D, 2D & plots
└── modules/ # Self-contained UI feature modules
├── start/ # Start Screen hub (/home), templates, import, recent work, instance discovery
├── ribbon/ # Discretization-aware Ribbon tabs & placeholder stripping
├── explorer/ # Five-tab semantic browser (Model, Resources, Results, Jobs, Diagnostics)
├── inspector/ # InspectorRegistry, route catalog & domain-specific semantic panels
├── viewport-3d/ # WebGL/Three.js R3F scene, studio HDRI & transparent/view PNG capture
├── field-map/ # 2D planar probe map, streamlines/contours, multislice & snapshot replay
├── live-charts/ # Real-time ECharts magnetization, energy & convergence traces
├── analysis-plots/ # ECharts dispersion, S(k,f) heatmap, Gamma FFT, FMR & hysteresis charts
├── analysis-*/ # Analysis feature modules (dispersion, hysteresis, resonance)
├── results-navigator/ # Durable SolutionSet browser & saved-result playback
├── overlay/ # Command Palette (Ctrl+Shift+P), MeshBuildDialog, notifications
├── footer/ # Bottom dock (Logs, Telemetry, Diagnostics, Engine, Operations/Mesh Jobs, Problems, Quick Chart)
└── status-bar/ # Live session state, readiness helper, mesh/compute progress
Module Manifest Contract¶
Every UI module exports a standardized manifest.ts defining its identity, contributed layout slots, menu actions, and ribbon buttons:
import type { ModuleManifest } from "@/kernel/types";
export const inspectorManifest: ModuleManifest = {
id: "inspector",
title: "Inspector",
version: "0.1.0",
slots: ["panel-right"],
component: () => import("./InspectorModule"),
};
This is the minimal shape from inspectorManifest; command contributions belong under
contributes.commands, with a run handler. Slot identifiers are the SlotId union;
"shell.right" is not a supported slot.
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).
Performance & Memory Safeguards¶
Instanced Mesh Glyphs: Vector field arrows and cones are rendered using
THREE.InstancedMeshwith GPU instancing to reduce draw-call overhead for large vector datasets.Binary ArrayBuffer Codecs: Field samples are fetched as scoped HTTP binary resources.
decodeFieldVectorvalidates the FMVP header, component count, revisions, indexing and an FP64 payload, then exposes aFloat64Array. Renderer-side GPU buffers are a separate representation. WebSocket events invalidate resources; they do not carry the field arrays.Context Loss Recovery: WebGL canvas lifecycle events (
webglcontextlost,webglcontextrestored) are monitored so rendering resources can be reconstructed after context restoration.Topology Caching: FEM mesh element topologies and node coordinates are cached separately from per-step vector field data, avoiding redundant GPU geometry re-uploads during time integration.
State Management & Invalidation Pipeline¶
Workspace state is maintained across three distinct tiers:
Selection & Layout Store: Tracks selected tree node IDs, panel visibility, ribbon tab index, and visual profile settings.
Draft Property Store: Holds transient uncommitted user edits in the Inspector before explicit application.
Session & Runtime Store: Synchronizes with the active backend session (
/v2/sessions/current/*), listening to WebSocket revision/invalidation events for stage completions, metric updates, and field invalidations.
User Input ──> Draft Store ──(Apply Draft)──> Session API ──> WebSocket Event ──> Viewport Invalidated ──> GPU Redraw
Technical Specifications¶
Subsystem |
Stack / Technology |
Key Files |
|---|---|---|
Framework |
Next.js 16 (React 19) |
|
3D Graphics |
Three.js / @react-three/fiber |
|
2D Charting |
ECharts / Recharts |
|
State |
Controllers / resource hooks / |
|
Transport |
OpenAPI v2 ( |
|
Styling |
CSS Custom Properties ( |
|
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¶
Claim |
Repository path |
Stable symbol |
|---|---|---|
Module and slot contracts |
|
|
Actual Inspector manifest |
|
|
HTTP resource facade |
|
|
WebSocket transport |
|
|
Event-to-resource invalidation |
|
|
Resource revision ownership |
|
|
FP64 field decoding |
|
|
These are source-level implementation references. This documentation review does not establish browser/WebGL execution or solver qualification.