@solidxai/core 0.1.13-beta.2 → 0.1.13-beta.4

package/docs/workflow/microservices-and-apis-example-notes.md

@@ -0,0 +1,264 @@
+# Microservices and APIs Example Notes
+
+## Purpose
+
+This document captures a third reference workflow focused on conditional branching and triggers. It is especially useful for the SolidX workflow UI because it shows how an `if / then / else` structure should appear in topology and how triggers can be visualized as a separate grouped area.
+
+---
+
+## Example Workflow YAML
+
+```yaml
+id: microservices-and-apis
+namespace: tutorial
+labels:
+  name: Microservices and APIs
+
+inputs:
+  - id: server_uri
+    type: URI
+    defaults: https://kestra.io
+
+  - id: slack_webhook_uri
+    type: URI
+    defaults: https://kestra.io/api/mock
+
+tasks:
+  - id: http_request
+    type: io.kestra.plugin.core.http.Request
+    description: Check the target server endpoint for an HTTP response.
+    uri: "{{ inputs.server_uri }}"
+    options:
+      allowFailed: true
+
+  - id: check_status
+    type: io.kestra.plugin.core.flow.If
+    description: Branch based on the HTTP status to alert or confirm health.
+    condition: "{{ outputs.http_request.code != 200 }}"
+    then:
+      - id: server_unreachable_alert
+        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
+        description: Send a Slack alert if the server cannot be reached.
+        url: "{{ inputs.slack_webhook_uri }}"
+        messageText: "The server {{ inputs.server_uri }} is down!"
+    else:
+      - id: healthy
+        type: io.kestra.plugin.core.log.Log
+        description: Log that the server is responding normally.
+        message: Everything is fine!
+
+triggers:
+  - id: daily
+    type: io.kestra.plugin.core.trigger.Schedule
+    disabled: true
+    cron: 0 9 * * *
+
+description: |
+  **Use case:** Simple microservice health check with conditional alerting.
+  **Schedule:** Disabled daily run at 09:00 to show how to automate recurring checks.
+  **Highlights:**
+  - Probe the target server and capture the HTTP response code.
+  - Branch on non-200 results to send a Slack webhook alert; otherwise log success.
+  - Parameterize the target URL and webhook for easy reuse across environments.
+```
+
+---
+
+## What This Example Adds
+
+This example is the clearest reference so far for:
+
+- `if / then / else` branching
+- visual trigger grouping
+- workflow inputs at the top level
+- branch child tasks inside a control-flow node
+- separate success and failure paths converging back into the main sequence
+
+---
+
+## High-Level Structure
+
+The workflow shape is:
+
+```text
+Triggers
+└── daily
+
+Main Flow
+http_request
+  |
+  v
+check_status
+  ├── then: server_unreachable_alert
+  └── else: healthy
+```
+
+Another useful representation is:
+
+```text
+Start
+  |
+  v
+[trigger group: daily]
+  |
+  v
+http_request
+  |
+  v
+check_status (If)
+  |-- then --> server_unreachable_alert
+  |-- else --> healthy
+  |
+  v
+End
+```
+
+---
+
+## Main New Note
+
+### Example With `if / then / else` Branching
+
+This is the key purpose of this example.
+
+It shows that a workflow topology renderer must support:
+
+- a control-flow node such as `If`
+- visually grouped child branches
+- separate `then` and `else` lanes
+- branch child nodes rendered inside the control-flow region
+- a visual merge back into the primary downstream flow
+
+This is not just nested sequencing. It is explicit branching.
+
+---
+
+## Trigger Visualization Notes
+
+This example also shows that triggers can be represented as a separate visual group from the main task sequence.
+
+Important implications:
+
+- triggers should not be treated as ordinary sequential tasks
+- trigger nodes should be rendered in their own grouped zone
+- the trigger group can visually connect into the main workflow start
+- disabled triggers should still be shown, likely with a muted or status-aware treatment
+
+For SolidX, this strongly suggests:
+
+- trigger rendering belongs in topology and editor views
+- trigger editing can still be delayed, but trigger visualization should be part of the long-term flow model
+
+---
+
+## Inputs Notes
+
+This example highlights workflow-level inputs:
+
+- `server_uri`
+- `slack_webhook_uri`
+
+That means the workflow-definition editor will eventually need a clean workflow-level configuration surface, not just task-level editing.
+
+Good future implications:
+
+- workflow metadata and inputs belong in code
+- later, they may also deserve a dedicated schema-driven modal or side panel
+
+---
+
+## Topology Notes
+
+The reference topology demonstrates three distinct visual concepts together:
+
+1. trigger group
+2. sequential task node
+3. branching control-flow group
+
+That makes this example especially valuable for validating the canvas contract.
+
+### Visual Behaviors Observed
+
+- the trigger sits inside a green grouped region
+- the `If` task sits inside a blue grouped region
+- the branch children appear inside that `If` region
+- the children are positioned as left and right alternatives
+- dashed directional connectors preserve the sense of control flow
+- the branch appears to rejoin the main vertical sequence
+
+---
+
+## Implications For SolidX Flow Modeling
+
+This example implies the React Flow layer must eventually support at least these structural categories:
+
+- simple task node
+- trigger node
+- trigger group container
+- control-flow node
+- branch container
+- branch child node
+
+Even if the first pass simplifies some of this, the metadata and transformation layer should be designed with these categories in mind.
+
+---
+
+## Edit-Screen Notes
+
+The edit screenshots again reinforce the desired authoring shell:
+
+- left: code
+- right: topology / flow
+- docs may be opened contextually when needed
+
+This example also shows the code and flow surfaces staying aligned while a structurally richer workflow is displayed.
+
+That is useful because it proves the editor cannot assume every workflow is purely linear.
+
+---
+
+## Control-Flow Contract Notes
+
+This example is a good reminder that the DSL remains the source of truth.
+
+For this workflow:
+
+- branch semantics come from the `If` node contract
+- branch children are defined by `then` and `else`
+- the canvas should reflect those semantics, not invent new ones
+
+So the flow renderer should be a structured projection of the DSL, not a freeform graph authoring tool.
+
+---
+
+## Pending Feature Notes
+
+This example highlights future needs:
+
+- dedicated trigger authoring UI
+- branch-aware flow rendering
+- grouped region handling for control-flow nodes
+- workflow-level input editing UX
+- branch-aware validation feedback in the editor
+
+---
+
+## Screenshot References
+
+These screenshots informed the notes above:
+
+- `/Users/harishpatel/Desktop/Screenshot 2026-07-10 at 17.11.11.png`
+- `/Users/harishpatel/Desktop/Screenshot 2026-07-10 at 17.11.22.png`
+- `/Users/harishpatel/Desktop/Screenshot 2026-07-10 at 17.11.43.png`
+
+---
+
+## Recommended Follow-On Use
+
+This example should be used as a reference for:
+
+1. `If` node rendering rules
+2. `then` / `else` lane visualization
+3. trigger-group rendering
+4. branch-aware layout logic
+5. future trigger and workflow-input editing UX

package/docs/workflow/samples.md

@@ -0,0 +1,25 @@
+curl -X POST "http://localhost:3000/api/workflow-definition/by-key/sample-workflow-builder-smoke-test/execute" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEsInVzZXJuYW1lIjoic2EiLCJlbWFpbCI6InNhQHNvbGlkeGFpLmNvbSIsInJvbGVzIjpbIkFkbWluIiwiSW50ZXJuYWwgVXNlciJdLCJpYXQiOjE3ODM2MTk0NzgsImV4cCI6MTc4MzcwNTg3OCwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDozMDAwIiwiaXNzIjoid29ya2Zsb3ctbWFuYWdlbWVudCJ9.58AqoXRkJkCE_U2nJVdhSrz_m-PrG47EnVOYpp3VGMY" \
+  -d '{
+    "triggerType": "manual",
+    "input": {
+      "name": "Harish",
+      "runHttp": true,
+      "url": "https://solidxai.com",
+      "items": ["alpha", "beta", "gamma"]
+    }
+  }'
+
+curl -X POST "http://localhost:3000/api/workflow-definition/by-key/sample-workflow-builder-smoke-test/execute" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEsInVzZXJuYW1lIjoic2EiLCJlbWFpbCI6InNhQHNvbGlkeGFpLmNvbSIsInJvbGVzIjpbIkFkbWluIiwiSW50ZXJuYWwgVXNlciJdLCJpYXQiOjE3ODM2MTk0NzgsImV4cCI6MTc4MzcwNTg3OCwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDozMDAwIiwiaXNzIjoid29ya2Zsb3ctbWFuYWdlbWVudCJ9.58AqoXRkJkCE_U2nJVdhSrz_m-PrG47EnVOYpp3VGMY" \
+  -d '{
+    "triggerType": "manual",
+    "input": {
+      "name": "Bhoomi",
+      "runHttp": true,
+      "url": "https://solidxai.com",
+      "items": ["item 1", "item 2", "item 3"]
+    }
+  }'

package/docs/workflow/what-is-kestra.md

@@ -0,0 +1,79 @@
+# What Is Kestra
+
+This note summarizes the Kestra Academy introduction lessons you shared so we have a common baseline before defining the workflow-management module for SolidX.
+
+## Summary
+
+Kestra presents workflow orchestration using the metaphor of an orchestra conductor. In the same way a conductor coordinates many musicians, a workflow orchestrator coordinates many systems, tools, and steps so work happens in the right order and at the right time.
+
+At a practical level, workflow orchestration is about:
+
+- Running multi-step processes in the correct sequence
+- Handling failures and retries in a controlled way
+- Triggering work from schedules or events
+- Giving operators visibility into execution progress and problems
+
+Kestra positions itself as an open-source orchestration platform that can support everything from small automations to large distributed pipelines. Its core framing is flexibility:
+
+- Workflows can be authored as code
+- Workflows can also be built visually
+- The platform is API-first and event-driven
+- It is language-agnostic, so each step can use the most suitable runtime
+- It is integration-heavy, with a broad plugin ecosystem for external systems
+
+The main idea is that Kestra is not limited to a single narrow use case. It is meant to be a general orchestration foundation for workflows that span systems, teams, and execution environments.
+
+## Key Characteristics Of Kestra
+
+### 1. Orchestration, not just scripting
+
+Kestra is not simply about writing a script with several commands. The orchestration layer is responsible for sequencing, triggering, error handling, observability, and operational control.
+
+### 2. Multiple authoring modes
+
+Kestra supports code-first and visual/no-code workflow creation. That is important for adoption because different users prefer different levels of abstraction.
+
+### 3. Event-driven and API-first
+
+This suggests workflows are not only scheduled jobs. They can also react to external events and be controlled programmatically.
+
+### 4. Language-agnostic execution
+
+A workflow step should not be tightly coupled to one programming language or runtime. The platform should coordinate heterogeneous tasks rather than force everything into a single stack.
+
+### 5. Integration as a first-class concern
+
+Kestra emphasizes connecting to databases, cloud services, APIs, storage, messaging systems, and operational tools. That means orchestration value comes from connecting existing systems reliably, not from replacing them.
+
+## Use Cases
+
+The linked Academy use-cases lesson is mostly a visual overview, but its message is clear: Kestra is intended to support a broad range of workflow patterns rather than one single domain.
+
+Reasonable use-case categories implied by the introduction are:
+
+- Data movement and transformation pipelines
+- Scheduled operational jobs and batch processing
+- API and system-to-system orchestration
+- Notifications, alerts, and downstream actions
+- Business process automation with dependent steps
+
+## What This Means For Our SolidX Module
+
+If we are building a reusable workflow-management module inspired by Kestra, this summary suggests a few important design principles:
+
+- We should treat workflow definition and workflow execution as separate but connected concerns.
+- We should support both technical and less-technical authoring experiences over time.
+- Triggers, retries, failure handling, and execution visibility should be part of the module’s foundation, not afterthoughts.
+- The module should orchestrate external systems cleanly instead of assuming all logic lives inside one runtime.
+- Reusability will depend on a strong plugin/action model and clean metadata boundaries.
+
+## Sources
+
+- [What is Workflow Orchestration?](https://academy.kestra.io/p/courses/kestra-fundamentals/3492611-introduction/11404069-what-is-workflow-orchestration)
+- [What is Kestra?](https://academy.kestra.io/p/courses/kestra-fundamentals/3492611-introduction/11404080-what-is-kestra)
+- [Use Cases](https://academy.kestra.io/p/courses/kestra-fundamentals/3492611-introduction/11404082-use-cases)
+
+## Notes
+
+- The first two lessons contained direct explanatory text.
+- The use-cases lesson was mostly image-based in the retrieved page, so the use-case categories above are a light inference from the lesson framing plus the surrounding Kestra introduction context.

package/docs/workflow/workflow-core-module-handoff-summary.md

@@ -0,0 +1,191 @@
+# Workflow Core Module Handoff Summary
+
+## Current Branches
+
+- `solid-core-module` work is on branch `ft-workflow`.
+- `solid-core-ui` also has a matching `ft-workflow` branch created from `dev`.
+- The original consuming project docs have been moved into `solid-core-module/docs/workflow`.
+
+## What We Built So Far
+
+Workflow functionality has been moved out of the consuming project and into `solid-core-module` so workflows become a first-class Solid Core feature.
+
+The backend now includes generated/core workflow models, controllers, services, repositories, DTOs, metadata, and a first-pass runtime engine. The current runtime supports seeded workflow definitions and execution through the workflow definition controller.
+
+## Workflow Models
+
+The agreed model set currently implemented is:
+
+- `WorkflowDefinition`
+- `WorkflowExecution`
+- `WorkflowStepExecution`
+- `WorkflowExecutionLog`
+- `WorkflowExecutionArtifact`
+- `WorkflowTriggerExecution`
+
+`WorkflowBlueprint` remains intentionally ignored for now.
+
+Definition versioning is represented as fields on definition and execution records rather than a separate version table.
+
+## Metadata And Tables
+
+Workflow metadata now lives in `src/seeders/seed-data/solid-core-metadata.json`.
+
+Workflow tables use the `ss_` prefix, for example:
+
+- `ss_workflow_definition`
+- `ss_workflow_execution`
+- `ss_workflow_step_execution`
+- `ss_workflow_execution_log`
+- `ss_workflow_execution_artifact`
+- `ss_workflow_trigger_execution`
+
+`workflowExecution.executionIdentifier` is now a normal `shortText` field because the runtime generates it directly. It is no longer modeled as a computed field.
+
+## Runtime And Node System
+
+The runtime uses a registry-based node provider model:
+
+- Node providers are registered through a decorator and interface pattern.
+- Discovery happens at module startup using Nest discovery/reflection.
+- The registry skips discovered wrappers that do not have a valid provider class `metatype`.
+
+The current v1 node/provider set includes:
+
+- `log.write`
+- `http.request`
+- `if`
+- `forEach`
+- `parallel`
+
+The workflow YAML shape uses ordered arrays with nested child arrays for control nodes, following the Kestra-style structure we agreed on.
+
+## Execution Flow
+
+Workflow execution is exposed through `WorkflowDefinitionController`:
+
+```bash
+POST /workflow-definition/by-key/:key/execute
+POST /workflow-definition/:id/execute
+```
+
+The sample seeded workflow key is:
+
+```text
+sample-workflow-builder-smoke-test
+```
+
+Example curl:
+
+```bash
+curl -X POST "http://localhost:3000/workflow-definition/by-key/sample-workflow-builder-smoke-test/execute" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -d '{
+    "triggerType": "manual",
+    "input": {
+      "name": "Harish",
+      "runHttp": false,
+      "url": "https://example.com",
+      "items": ["alpha", "beta", "gamma"]
+    }
+  }'
+```
+
+## Workflow Execution Relations
+
+`WorkflowExecution` now has contextual one-to-many relations for:
+
+- `workflowStepExecutions`
+- `workflowExecutionLogs`
+- `workflowExecutionArtifacts`
+
+These are exposed as tabs in the Workflow Execution form. The child models are not marked with `isChild: true`; that flag is reserved for another SolidX use case.
+
+Standalone menu items for step executions, logs, and artifacts were removed because these records are intended to be viewed in the context of a workflow execution.
+
+`WorkflowTriggerExecution` remains as a standalone menu item because trigger executions can conceptually exist independently from a completed workflow execution.
+
+## Admin Metadata UI Changes
+
+Workflow menus are grouped under a top-level `Workflow` menu, similar to the existing Layout Builder pattern.
+
+Workflow Definition form:
+
+- `Basic Info`
+- `Definition YAML`
+
+Workflow Execution form:
+
+- `Basic Info`
+- `Input`
+- `Output`
+- `Definition Snapshot`
+- `Steps`
+- `Logs`
+- `Artifacts`
+- `Errors`
+
+JSON fields in the dedicated JSON tabs use metadata-only layout attributes:
+
+- `className` on the field wrapper
+- `height` passed to `SolidCodeEditor`
+
+The JSON editor height is currently set with viewport-based values such as:
+
+```json
+"height": "calc(100vh - 260px)"
+```
+
+## Seeding
+
+`ModuleMetadataSeederService` was updated to seed workflow definitions from module metadata JSON.
+
+The consuming project currently still owns a sample workflow metadata file under:
+
+```text
+solid-api/src/workflow-builder/metadata/workflow-builder-metadata.json
+```
+
+That sample is useful for smoke testing the runtime.
+
+## Important Decisions
+
+- Workflow definitions are not treated as a single opaque blob internally, but they do have a canonical YAML DSL for sharing, seeding, validation, and developer workflows.
+- Runtime data belongs in execution records/context, not in the definition YAML.
+- New workflow node types should be registry-driven from day one.
+- JSON fields are processed in memory to keep the workflow engine DB agnostic.
+- Revisions/version tables are deferred; version/checksum fields are sufficient for now.
+
+## Recent Verification
+
+The following has passed after the latest workflow-related changes:
+
+```bash
+npm run build
+```
+
+Run it from:
+
+```text
+/Users/harishpatel/Code/javascript/solid-core-module
+```
+
+## Moved Design Docs
+
+The original design docs are now under this folder:
+
+```text
+docs/workflow
+```
+
+Key docs include:
+
+- `what-is-kestra.md`
+- `kestra-concepts-plugins-blueprints.md`
+- `workflow-module-brd.md`
+- `workflow-module-technical-spec.md`
+- `workflow-module-domain-model.md`
+- `workflow-module-metadata-dsl.md`
+- `workflow-node-type-contracts.md`
+- `workflow-solidx-model-field-spec.md`