@solidxai/core 0.1.13-beta.11 → 0.1.13-beta.13

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

@@ -1,264 +0,0 @@
-# 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

@@ -1,25 +0,0 @@
-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

@@ -1,79 +0,0 @@
-# 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

@@ -1,191 +0,0 @@
-# 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`