Workflow visualizer prototype #1335

wenli-cai · 2025-06-05T13:30:08Z

Given snapshots of all workflows, the visualizer shows a tree-like structure to allow developers to have an easier time of debugging through state changes and render passes

Current progress

Basic sandbox-y background to allow free movement
Given a simple json data to represent each WorkflowNode, a basic tree structure can be drawn; these nodes can also be opened and closed upon clicking
Arrows to show relationship between nodes, however this is currently bugged and not in the right location

- Allows users to freely zoom and pan to view different sections of the tree

The attributes of each node is tightly coupled with the content of the json, so any changes to the JSON will lead to an error unless the WorkflowNode class is also changed accordingly.

…ow node - arrows start with a weird offset in the beginning relative to where the nodes are

CLAassistant · 2025-06-05T13:30:15Z

All committers have signed the CLA.

…Snapshot Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

japplin · 2025-06-05T14:53:45Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/App.kt

@@ -5,5 +5,12 @@ import androidx.compose.runtime.Composable

 @Composable
 fun App() {
-  Text("Hello world!")
+  val jsonString = object {}.javaClass.getResource("/workflow-simple.json")?.readText()


I think getClass().getResource should work here

- if modifier is set to unbounded, content also needs to be aligned.

- Density of displays caused weird errors of how the arrows appear - Scaling and translating the arrow positions was also separate from the movement of the nodes

- Figuring out how to lay out arrows was unnecessarily difficult, and ended up being too distracting, so utilizing the column space each node and its children are in was a much cleaner way to represent a subtree relationship - Figure will closely resemble a treemap

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

steve-the-edwards · 2025-06-09T14:53:55Z

workflow-trace-viewer/build.gradle.kts

@@ -23,6 +23,8 @@ kotlin {
        implementation(compose.desktop.currentOs)
        implementation(libs.kotlinx.coroutines.swing)
        implementation(compose.materialIconsExtended)
+        implementation(libs.moshi.kotlin)
+        implementation("io.github.vinceglb:filekit-dialogs-compose:0.10.0-beta03")


Add this to gradle/libs.versions.toml and then reference it here rather than the direct include (eases maintenance).

steve-the-edwards · 2025-06-09T14:58:24Z

...flow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/SandboxBackground.kt

+    modifier
+      .fillMaxSize()
+      .pointerInput(Unit) {
+        // this allows for user's panning to view different parts of content


Suggested change

// this allows for user's panning to view different parts of content

// This allows for user's panning to view different parts of content.

All comments should be sentences and use punctuation as such.

Here and elsewhere.

Done and fixed all other grammatical errors in comments.

steve-the-edwards · 2025-06-09T14:58:59Z

...flow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/SandboxBackground.kt

+      .fillMaxSize()
+      .pointerInput(Unit) {
+        // this allows for user's panning to view different parts of content
+        awaitEachGesture {


Is this from a blog post or ref article or something? If so, it can be valuable to post the link in a comment as then we can follow up during maintenance.

Added note that code is AI generated.

steve-the-edwards · 2025-06-09T15:00:58Z

...flow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/SandboxBackground.kt

+          if (drag != null && drag.pressed) {
+            var prev = drag.position
+            while (true) {
+              val nextEvent = awaitPointerEvent()


there is no way to get stuck here right? As in, is it possible we already captured event.changes but those were all of them and there is nothign to await()? or is this await()ing changes we already know we have?

Changed functionality with higher-level onDragGestures API from Android

steve-the-edwards · 2025-06-09T15:02:09Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/UploadFile.kt

+import io.github.vinceglb.filekit.dialogs.compose.rememberFilePickerLauncher
+
+@Composable
+public fun UploadFile(


Needs kdoc.

steve-the-edwards · 2025-06-09T15:03:11Z

...low-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/WorkflowJsonParser.kt

+ * All the caught exceptions should be handled by the caller, and appropriate UI feedback should be
+ * provided to user
+ */
+public fun fetchRoot(


Maybe change name to parseTrace or something? fetchRoot does not communicate all that it is doing, even though the root WorkflowNode? is what is returned.

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

wardellbagby · 2025-06-10T17:06:24Z

This was a miss on a previous PR (the Kotlin 2.0 one and my own one adding this module...) but we need to add .kotlin to the .gitignore and not commit the changes in it to the repo. Feel free to take a crack at that, 'cause it'd be nice to have it apart of this PR so we don't commit the changes you already have made to it.

steve-the-edwards · 2025-06-10T17:12:09Z

This was a miss on a previous PR (the Kotlin 2.0 one and my own one adding this module...) but we need to add .kotlin to the .gitignore and not commit the changes in it to the repo. Feel free to take a crack at that, 'cause it'd be nice to have it apart of this PR so we don't commit the changes you already have made to it.

@wardellbagby , do you mean .klib? I was wondering what the typical practice is. But adding it to gitignore sounds good!

steve-the-edwards

LGTM. A couple things still before merge:

Add the .klib to .gitignore as @wardellbagby was suggesting
get sign off from someone more well versed with Compose then me (@wardellbagby , @zach-klippenstein, etc.)

steve-the-edwards · 2025-06-10T17:13:29Z

...flow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/SandboxBackground.kt

+        detectDragGestures { _, translation->
+          offset += translation
+        }


wardellbagby

Left a few comments for you but all in all, this does look great!

wardellbagby · 2025-06-10T17:10:40Z

gradle/libs.versions.toml

@@ -3,7 +3,10 @@
 agpVersion = "8.8.0"

 compileSdk = "34"
+# Any version above 0.10.0-beta03 requires Compose 1.8.0 or higher.
+filekitDialogsComposeVersion = "0.10.0-beta03"


Let's stick with the same naming convention we have here. Android SDK versions get camel case but dependency versions use kebab-case. In that same vein, dependencies should be named without the version suffix.

So this would be filekit-dialogs-compose, Moshi would be moshi-kotlin, and uiGraphicsAndroidVersion would be androidx-ui-graphics-android.

This is also is roughly alphabetical order, with spacings denoting group separations for when we have many dependencies all related to the same thing, like androidx, so this and the other new versions should be listed in that same order.

It's ultimately a small thing admittedly, but it's always good to be consistent 'cause then things tend to stay how you'd expect them to be when you come back later!

wardellbagby · 2025-06-10T17:15:45Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/App.kt

+  modifier: Modifier = Modifier
+) {
+  Box {
+    val selectedFile = remember { mutableStateOf<PlatformFile?>(null) }


Prefer using Kotlin delegation here.

var selectedFile by remember { mutableStateOf<PlatformFile?>(null) }

That'll let you do simple reassignments without having to do the whole .value stuff to access or change the value. Android Studio will try to prompt you to import the getValue and setValue extension methods that make that possible, but if it doesn't, you may need to manually import them.

An example of this syntax is here: https://github.com/squareup/android-emulator-runner/blob/92d600d5e9cb215e3509ee215881e55a42fb6fac/desktop-app/src/jvmMain/kotlin/com/wardellbagby/aer/ui/App.kt#L192

The imports you may need to add manually are:

import androidx.compose.runtime.getValue import androidx.compose.runtime.setValue

wardellbagby · 2025-06-10T17:30:03Z

...low-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/WorkflowJsonParser.kt

+ * All the caught exceptions should be handled by the caller, and appropriate UI feedback should be
+ * provided to user.
+ */
+public fun parseTrace(


JSON parsing can be long running. This would be better as a suspend fun that wraps this work in a withContext(Dispatchers.IO) block. Then, instead of having a jsonString being used as state in your WorkflowContent Composable, you'd have a nullable WorkflowNode.

That would make WorkflowContent look something like this:

@Composable private fun WorkflowContent(file: PlatformFile?) { var rootNode by remember { mutableStateOf<WorkflowNode?>(null) } LaunchedEffect(file) { if(file != null) { rootNode = parseTrace(file?.readString()) // in the future, a try-catch here to switch to an error state! } } if (rootNode != null) { DrawWorkflowTree(root) } else { Text("Empty data or failed to parse data") // TODO: proper handling of error } }

For the future, when you get to the point where you might wanna show an error on parse failures, you'd instead just let this throw and expect it to be caught in the LaunchedEffect you call this from so that the consumer could switch to some error state. But that's looking ahead so don't stress that now!

Working on this in another branch!

wardellbagby · 2025-06-10T17:31:55Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/App.kt

+}
+
+@Composable
+private fun WorkflowContent(file: PlatformFile?) {


Nit: No need for file to be nullable here. I imagine it's because Kotlin thinks .value can change but we know it won't so it's okay to use !! here to force it to be non-null.

wardellbagby · 2025-06-10T17:46:18Z

workflow-trace-viewer/src/jvmMain/kotlin/com/squareup/workflow1/traceviewer/WorkflowTree.kt

+  node: WorkflowNode,
+  modifier: Modifier = Modifier,
+) {
+  Column(


This works fine for now but eventually, we're probably gonna have to get lazy with it. I'm not familiar with it but I recently learned that Compose has a LazyLayout Composable that, similar to LazyRow and LazyColumn, lets you render a bunch of stuff but is smart enough to only render things that are actually in view. Since these traces are gonna get big, we'll start to see lagging when scrolling. We might already with your workflow-300 trace!

I can probably bully one of the UI System folks for more info on how we could potentially use that here, since the documentation is really sparse and LazyLayout is still experimental.

workflow-300 seems to be fine when scrolling for now... but I will keep this in mind in the future once the traces get very large.

wardellbagby · 2025-06-10T17:48:22Z

@wardellbagby , do you mean .klib? I was wondering what the typical practice is. But adding it to gitignore sounds good!

@steve-the-edwards Nah, the whole .kotlin folder should be ignored. Everything in there is just local to the machine building it. That folder used to stored in .gradle, which we similarly ignore but I guess that changed with Kotlin 2 so not we have to get specific.

wenli-cai added 4 commits June 4, 2025 11:41

Create sandbox-type background for app

dceb9e4

- Allows users to freely zoom and pan to view different sections of the tree

Create json parsing using moshi

759e3e4

Draw workflow nodes through the given classes

efdaa92

The attributes of each node is tightly coupled with the content of the json, so any changes to the JSON will lead to an error unless the WorkflowNode class is also changed accordingly.

WIP provide temporary solution for drawing arrows between each workfl…

56de1f6

…ow node - arrows start with a weird offset in the beginning relative to where the nodes are

wenli-cai assigned steve-the-edwards Jun 5, 2025

wenli-cai requested review from zach-klippenstein and a team as code owners June 5, 2025 13:30

Apply changes from connectedCheckShardMatrixYamlUpdate checkVersionIs…

f2ec953

…Snapshot Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

japplin reviewed Jun 5, 2025

View reviewed changes

wenli-cai marked this pull request as draft June 5, 2025 17:22

wenli-cai and others added 8 commits June 5, 2025 13:29

Fixed arrow positioning

6dbd1ff

- if modifier is set to unbounded, content also needs to be aligned.

WIP drawing arrows

d192bab

- Density of displays caused weird errors of how the arrows appear - Scaling and translating the arrow positions was also separate from the movement of the nodes

fix bug that limited the area for .pointerInput

e964c42

create upload button for downloaded json/txt files

97f8e77

minor QOL changes in appearance

e947472

Apply changes from apiDump

35567b1

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

clean up imports and comments to ready PR

761c987

steve-the-edwards requested review from steve-the-edwards, wardellbagby and a team June 6, 2025 14:22

wenli-cai and others added 2 commits June 6, 2025 11:43

Fix ktlint issues

e212736

Apply changes from apiDump

03d7784

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

wenli-cai marked this pull request as ready for review June 6, 2025 15:59

wenli-cai changed the title ~~WIP: wenli/workflow viewer~~ wenli/workflow viewer Jun 9, 2025

wenli-cai changed the title ~~wenli/workflow viewer~~ Workflow visualizer prototype Jun 9, 2025

steve-the-edwards reviewed Jun 9, 2025

View reviewed changes

wenli-cai and others added 2 commits June 10, 2025 12:46

Edits made for PR comments

0f8e334

Apply changes from apiDump

a1099dc

Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

wenli-cai force-pushed the wenli/workflow-viewer branch from c968d7f to a1099dc Compare June 10, 2025 16:46

steve-the-edwards approved these changes Jun 10, 2025

View reviewed changes

wardellbagby reviewed Jun 10, 2025

View reviewed changes

wenli-cai added 2 commits June 10, 2025 15:28

Fix more PR feedback

f9a64ff

Removed .kotlin/ metadata

e36ca77

wardellbagby approved these changes Jun 10, 2025

View reviewed changes

Merge branch 'main' into wenli/workflow-viewer

a778895

wenli-cai merged commit 784e757 into main Jun 11, 2025
45 checks passed

wenli-cai deleted the wenli/workflow-viewer branch June 11, 2025 13:39

	// this allows for user's panning to view different parts of content
	// This allows for user's panning to view different parts of content.

Workflow visualizer prototype #1335

Workflow visualizer prototype #1335

Uh oh!

Conversation

wenli-cai commented Jun 5, 2025

Current progress

Uh oh!

CLAassistant commented Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wardellbagby commented Jun 10, 2025

Uh oh!

steve-the-edwards commented Jun 10, 2025

Uh oh!

steve-the-edwards left a comment • edited by wenli-cai Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wardellbagby left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wardellbagby commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CLAassistant commented Jun 5, 2025 •

edited

Loading

steve-the-edwards left a comment •

edited by wenli-cai

Loading

wardellbagby commented Jun 10, 2025 •

edited

Loading