Document making Flows stable (Freecords Dashboard) #1
Conversation
This document outlines architectural changes made to improve the reliability of Kendraio Flows, focusing on design patterns for stability during batch operations. Key concepts include conditional guards, context bridges, explicit state restoration, and enhancements for developer experience.
CodeKrakken
left a comment
CodeKrakken
left a comment
There was a problem hiding this comment.
Great write-up @lukestanley - no complaints with the text, just a few formatting suggestions.
| ### Conditional guards | ||
|
|
||
| **The concept** | ||
| In the original workflow, the verification loop blindly attempted to re-download every asset associated with a song to check its integrity. However, real-world data is messy: not every song has artwork, and not every release has a specific audio format. If the flow attempts to run an HTTP fetch on a `null` or empty URL, the block fails. This generates error noise or stops the flow entirely. |
There was a problem hiding this comment.
We could maybe do with a new line, a hyphen or a bit more space to differentiate the bold text here (and in subsequent similar situations).
| "type": "http", | ||
| "method": "get", | ||
| "blockComment": "📥 Fetch original artwork for comparison" | ||
| } |
There was a problem hiding this comment.
Might be clearer to have a full http example for the uninitiated. Or just a comment to represent the missing config (for example ...config...)
| %%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ffffff', 'primaryTextColor': '#000000', 'primaryBorderColor': '#000000', 'lineColor': '#000000', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff'}}}%% | ||
| A[Grid Selection] --> B[Batch: Upload] | ||
| B --> C[Output: Upload Results] | ||
| C -.-> D[Discard Results] |
There was a problem hiding this comment.
I found 'Output: Upload Results' confusing as a button label at first glance - I read Upload as a verb. Perhaps these could be 'Batch: Upload Request', 'Output: Upload Response' and 'Discard Response'.
|
|
||
| ### Developer experience: Comment navigation aid | ||
|
|
||
| To make these complex batch flows maintainable, a visual annotation system was introduced within the `blockComment` fields. Specific emojis are used to denote the function of the block. This allows a developer to scan the JSON definition or the UI and instantly understand the "shape" of the logic without reading the configuration of every individual block. |
There was a problem hiding this comment.
Could be helpful to formalise the use of these visual symbols, but we should define them somewhere.
| The core features, specifically the logic for grouping tracks into DDEX XML and the concept of a post-upload verification loop, were already present in the base system. This post isolates the architectural changes implemented on top of those existing features. The focus lies on the patterns added to make the system stable, robust, and crash-proof in a production batch environment. | ||
|
|
||
| ### Conditional guards | ||
|
|
There was a problem hiding this comment.
This heading should not be larger than the main heading.
This document outlines architectural changes made to improve the reliability of Kendraio Flows, focusing on design patterns for stability during batch operations. Key concepts include conditional guards, context bridges, explicit state restoration, and enhancements for developer experience.
See it rendered here: https://github.com/kendraio/kendraio-gists/blob/stable_http_block_patterns/stable_flows.md