06 — User and developer flows¶

Developer-level end-to-end sequences: every hop named, L5 app → L4 shell → L3 EngineHost → L2 C ABI → L1 engine. For the click-level, per-control view of the same gestures see ../../slicer/workflows.md and ../../simulator/workflows.md. Abbreviations: SA = src/SlicerApp, SI = src/SimulatorApp, SH = src/Nps.Shell, EH = src/Nps.EngineHost.

App boot¶

sequenceDiagram
    participant OS
    participant Program as Program.Main
    participant App as Avalonia App
    participant MW as MainWindow
    participant ES as EngineSession
    participant VP as ViewportController
    participant ABI as "NpsAbi / NPSEngine"

    OS->>Program: start process
    Program->>ABI: ABI gate (version assert)
    Program->>ABI: CLI preflight (session + fixture load)
    Program->>App: BuildAvaloniaApp().StartWithClassicDesktopLifetime
    App->>MW: new MainWindow
    MW->>MW: InitializeShell (wire chrome + events)
    MW->>ES: CreateAndInitialize()
    ES->>ABI: CreateEngine + InitializeEngine
    MW->>VP: CreateAndInitialize()
    VP->>ABI: CreateGcodeViewport
    MW->>MW: "Status(shell ready)"

The GUI session in step 7 is a second engine instance; the CLI preflight session is disposed (→ DestroyEngine) before the window opens.

Load → demo gen → analyze → viewport¶

Primary button path (OnLoadAnalyzeClick — SA/MainWindow.axaml.cs:155 / SI/MainWindow.axaml.cs:205).

sequenceDiagram
    participant U as User
    participant MW as MainWindow
    participant FL as FixtureLocator
    participant ES as EngineSession
    participant Eng as nps::Engine
    participant VP as ViewportController
    participant UI as Canvas/Status

    U->>MW: click Load + Gen + Analyze
    MW->>FL: FindPrimaryBenchy3Mf()
    FL-->>MW: path or missing
    alt fixture missing
        MW->>UI: "ERROR: primary 3mf required"
    else ok
        MW->>ES: LoadModel(path)
        ES->>Eng: "LoadModelFromFile (ZIP/OPC → ModelXML → MeshResolver)"
        Eng-->>ES: plates, verts, tris, palette, unit
        ES-->>MW: LoadResult
        MW->>UI: Status mesh summary
        MW->>ES: GenerateDemoToolpath(options)
        Note over ES,Eng: "DEMO TOOLPATH — not production slice"
        ES->>Eng: GenerateGcode
        Eng-->>ES: engine-owned move array
        MW->>VP: SetMoves(LastMovesPointer, count)
        MW->>VP: SetLayerVisibility + SetCamera + BuildBuffers
        MW->>ES: Analyze(profile)
        ES->>Eng: AnalyzeGcode (6 analyzers)
        MW->>MW: LoadFindings (16B summary rows)
        MW->>UI: RenderViewport + Status(DEMO TOOLPATH…)
    end

Ordered steps (code)¶

Golden-fixture expectation after step 2: 1 plate / 16562 verts / 33097 tris / 4 palette colors.

Parse path (ParseGcode / ParseBgcode)¶

No app UI path exists today. Neither app has an open/paste G-code gesture and EngineSession exposes no Parse facade; every caller is a test harness (SH/ViewportController.cs:235 notes the "future ParseGcode path"). What matters architecturally:

Finding click → detail¶

sequenceDiagram
    participant U as User
    participant FP as FindingsPanel
    participant MW as MainWindow
    participant ES as EngineSession
    participant Eng as Engine

    U->>FP: select finding row
    FP->>FP: UpdateDetail(item)
    FP->>MW: FindingSelected(item)
    MW->>FP: TryGetCachedItem(findingId)
    alt cache miss
        MW->>ES: GetFindingDetail(findingId)
        ES->>Eng: GetAnalysisFindingsDetail
        Eng-->>ES: 300B category/message/suggestion
    end
    MW->>MW: status + layer bump + highlight

Preferred ABI path honored: 16-byte NpsAnalysisFindingSummary rows first (EH/NpsAbi.cs:180), one 300-byte NpsAnalysisFinding detail per selection (:161, :461).

Overlay application¶

sequenceDiagram
    participant U as User
    participant MW as MainWindow
    participant ES as EngineSession
    participant VP as ViewportController

    U->>MW: choose overlay mode
    MW->>VP: ApplyOverlay(session, mode)
    loop each move index
        VP->>ES: GetOverlayValue(mode, layer, i)
    end
    VP->>VP: "one-shot ViewportApplyOverlay (NpsAbi.cs:432)"
    MW->>MW: RenderViewport (heatmap via ViewportGetHeatmapColor)

• Radio "None" maps to mode id motion-type, not a no-op (SH/Controls/OverlayPanel.axaml:10 Tag); motion-type renders as the inactive/plain path (SH/ViewportController.cs:576).
• Apps call the session overload ViewportController.ApplyOverlay(session, mode) SH/ViewportController.cs:564; it fetches per-move values via EngineSession.GetOverlayValue (:588 → EH/EngineSession.cs:486) and finishes with the one-shot export ViewportApplyOverlay EH/NpsAbi.cs:432.
• warp-risk additionally auto-enables deformation SetWarpParams(true, 5.0f) SH/ViewportController.cs:627-634; any other mode sets (false, 0).
• After every Load+Gen+Analyze both apps force the thermal overlay (SA:305-312 / SI:288-295).

Playback (Simulator only)¶

sequenceDiagram
    participant U as User
    participant MW as MainWindow
    participant T as DispatcherTimer
    participant VP as ViewportController

    U->>MW: press P (play)
    MW->>T: start (120 / speed ms)
    loop tick
        T->>MW: StepPlayback(+1)
        MW->>VP: SetSimulationState(true, ++SimMoveIndex)
        MW->>MW: RenderViewport progressive
        opt hit finding within 2 moves
            MW->>T: stop (auto-pause)
        end
    end
    U->>MW: P again (pause)

In SlicerApp there is no playback tab (SA/MainWindow.axaml:20) and P/Left/Right only emit Status("Playback unavailable in Slicer.") (SA:142-144).

Gates¶

Developer: build / test / run¶

cmake -B build -S src/Engine -DBUILD_TESTING=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
ctest --test-dir build --output-on-failure

DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 $HOME/.dotnet/dotnet test

# apps (native lib on LD_LIBRARY_PATH / build dir)
./start-gui.sh   # or project-specific launch

See also¶

• shell-and-apps.md
• engine-host.md
• engine-modules.md
• ../../slicer/workflows.md — click-level Slicer view
• ../../simulator/workflows.md — click-level Simulator view