Add flow specification with traderx examples (#463)

* Add flow specification with traderx examples * change validation rule to just run instantiation rules on the instantiation example as don't apply to flows --------- Co-authored-by: Matthew Bain <66839492+rocketstack-matt@users.noreply.github.com>
finos · Oct 11, 2024 · 6d43880 · 6d43880
1 parent 62e2074
commit 6d43880
Show file tree

Hide file tree

Showing 13 changed files with 742 additions and 1 deletion.
diff --git a/.github/workflows/spectral-validation.yml b/.github/workflows/spectral-validation.yml
@@ -31,5 +31,5 @@ jobs:
         with:
           node-version: v20
       - run: npm install @stoplight/spectral-cli
-      - run: npx spectral lint --ruleset spectral/instantiation/validation-rules.yaml 'calm/samples/**/*(*.json|*.yaml)'
+      - run: npx spectral lint --ruleset spectral/instantiation/validation-rules.yaml 'calm/samples/api-gateway-instantiation(*.json|*.yaml)'
 
diff --git a/calm/draft/2024-10/meta/flow.json b/calm/draft/2024-10/meta/flow.json
@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://calm.finos.org/draft/2024-10/meta/flow.json",
+  "title": "Business Flow Model",
+  "description": "Defines business flows that relate to technical architectures, allowing mapping of flows to technical components and attaching control requirements.",
+  "type": "object",
+  "properties": {
+    "unique-id": {
+      "type": "string",
+      "description": "Unique identifier for the flow"
+    },
+    "name": {
+      "type": "string",
+      "description": "Descriptive name for the business flow"
+    },
+    "description": {
+      "type": "string",
+      "description": "Detailed description of the flow's purpose"
+    },
+    "requirement-url": {
+      "type": "string",
+      "description": "Link to a detailed requirement document"
+    },
+    "transitions": {
+      "type": "array",
+      "items": {
+        "$ref": "#/defs/transition"
+      }
+    },
+    "controls": {
+      "$ref": "https://calm.finos.org/draft/2024-10/meta/control.json#/defs/controls"
+    },
+    "metadata": {
+      "$ref": "#/defs/metadata"
+    }
+  },
+  "required": [
+    "unique-id",
+    "name",
+    "description",
+    "transitions"
+  ],
+  "defs": {
+    "transition": {
+      "type": "object",
+      "properties": {
+        "relationship-unique-id": {
+          "type": "string",
+          "description": "Unique identifier for the relationship in the architecture"
+        },
+        "sequence-number": {
+          "type": "integer",
+          "description": "Indicates the sequence of the relationship in the flow"
+        },
+        "summary": {
+          "type": "string",
+          "description": "Functional summary of what is happening in the transition"
+        },
+        "direction": {
+          "enum": [
+            "source-to-destination",
+            "destination-to-source"
+          ],
+          "default": "source-to-destination"
+        },
+        "required": [
+          "relationship-unique-id",
+          "sequence-number",
+          "summary"
+        ]
+      },
+      "minItems": 1
+    },
+    "metadata": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    }
+  }
+}
+
diff --git a/calm/samples/traderx/controls/flow-sla-control-requirement.json b/calm/samples/traderx/controls/flow-sla-control-requirement.json
@@ -0,0 +1,182 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://calm.finos.org/traderx/controls/flow-sla-control-requirement.json",
+  "title": "Flow SLA Control",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "https://calm.finos.org/draft/2024-10/meta/control-requirement.json"
+    }
+  ],
+  "properties": {
+    "control-id": {
+      "const": "flow-sla-001"
+    },
+    "name": {
+      "const": "Flow SLA Control"
+    },
+    "description": {
+      "const": "Ensure that each flow meets the defined Service Level Agreement (SLA)"
+    },
+    "latency": {
+      "type": "object",
+      "properties": {
+        "expected-latency": {
+          "$ref": "https://calm.finos.org/draft/2024-10/meta/units.json#/defs/time-unit",
+          "description": "The expected latency for completion of flow"
+        },
+        "alert-threshold": {
+          "$ref": "https://calm.finos.org/draft/2024-10/meta/units.json#/defs/time-unit",
+          "description": "If latency exceeds this threshold, an alert will be triggered."
+        }
+      },
+      "required": [
+        "expected-latency",
+        "alert-threshold"
+      ]
+    },
+    "throughput": {
+      "type": "object",
+      "properties": {
+        "expected-message-rate": {
+          "$ref": "https://calm.finos.org/draft/2024-10/meta/units.json#/defs/time-unit",
+          "description": "Define the expected message rate that the flow should handle e.g. 1000 per second"
+        }
+      },
+      "required": [
+        "expected-message-rate"
+      ]
+    },
+    "availability": {
+      "type": "object",
+      "properties": {
+        "uptime-guarantee": {
+          "type": "number",
+          "description": "Percentage of availability required (e.g., 99.9%).",
+          "minimum": 0,
+          "maximum": 100
+        }
+      },
+      "required": [
+        "uptime-guarantee"
+      ]
+    },
+    "data-integrity": {
+      "type": "object",
+      "properties": {
+        "message-reliability": {
+          "enum": [
+            "atLeastOnce",
+            "atMostOnce",
+            "exactlyOnce"
+          ],
+          "description": "Guarantee that messages are delivered in the correct order and without duplication."
+        },
+        "loss-tolerance": {
+          "type": "number",
+          "description": "Specify acceptable levels of message loss as a percentage (e.g., 0 to 100).",
+          "minimum": 0,
+          "maximum": 100
+        }
+      },
+      "required": [
+        "message-reliability",
+        "loss-tolerance"
+      ]
+    },
+    "error-handling": {
+      "type": "object",
+      "properties": {
+        "retry-logic": {
+          "type": "object",
+          "properties": {
+            "max-retries": {
+              "type": "integer",
+              "description": "Specify the maximum number of retries in case of failures."
+            },
+            "retry-interval": {
+              "$ref": "https://calm.finos.org/draft/2024-10/meta/units.json#/defs/time-unit",
+              "description": "Define the interval between retries."
+            }
+          },
+          "required": ["max-retries", "retry-interval"]
+        }
+      },
+      "required": [
+        "retry-logic"
+      ]
+    },
+    "monitoring": {
+      "type": "object",
+      "properties": {
+        "real-time-monitoring": {
+          "type": "string",
+          "description": "Define the monitoring systems for tracking performance against the SLA."
+        },
+        "consumer-reporting": {
+          "$ref": "https://calm.finos.org/draft/2024-10/meta/units.json#/defs/time-unit",
+          "description": "Specify the reporting frequency for the consumer, e.g., daily, weekly, or monthly."
+        }
+      },
+      "required": [
+        "real-time-monitoring",
+        "consumer-reporting"
+      ]
+    },
+    "incident-response": {
+      "type": "object",
+      "properties": {
+        "incident-resolution-time": {
+          "$ref": "https://calm.finos.org/draft/2024-10/meta/units.json#/defs/time-unit",
+          "description": "Define timeframes for responding to SLA-impacting issues."
+        },
+        "escalation-protocols": {
+          "type": "object",
+          "properties": {
+            "incident-start-time-post-alert": {
+              "$ref": "https://calm.finos.org/draft/2024-10/meta/units.json#/defs/time-unit",
+              "description": "Timeframe for initiating incident response after an alert."
+            },
+            "escalation-path": {
+              "type": "string",
+              "description": "Specify the escalation path for SLA violations."
+            }
+          },
+          "required": [
+            "incident-start-time-post-alert",
+            "escalation-path"
+          ]
+        }
+      },
+      "required": [
+        "incident-resolution-time",
+        "escalation-protocols"
+      ]
+    },
+    "review-adjustments": {
+      "type": "object",
+      "properties": {
+        "sla-review": {
+          "$ref": "https://calm.finos.org/draft/2024-10/meta/units.json#/defs/time-unit",
+          "description": "Outline a schedule for regularly reviewing the SLA."
+        }
+      },
+      "required": [
+        "sla-review"
+      ]
+    }
+  },
+  "required": [
+    "control-id",
+    "name",
+    "description",
+    "latency",
+    "throughput",
+    "availability",
+    "data-integrity",
+    "error-handling",
+    "monitoring",
+    "incident-response",
+    "review-adjustments"
+  ]
+}
diff --git a/calm/samples/traderx/flows/add-update-account/add-update-account-control-configuration.json b/calm/samples/traderx/flows/add-update-account/add-update-account-control-configuration.json
@@ -0,0 +1,65 @@
+{
+  "$schema": "https://calm.finos.org/traderx/controls/flow-sla-control-requirement.json",
+  "$id": "https://calm.finos.org/traderx/flows/add-update-account/add-update-account-control-configuration.json",
+  "control-id": "flow-sla-001",
+  "name": "Flow SLA Control for Add or Update Account",
+  "description": "Ensure that the Add or Update Account flow meets the defined Service Level Agreement (SLA).",
+  "latency": {
+    "expected-latency": {
+      "value": 100,
+      "unit": "milliseconds"
+    },
+    "alert-threshold": {
+      "value": 150,
+      "unit": "milliseconds"
+    }
+  },
+  "throughput": {
+    "expected-message-rate": {
+      "value": 500,
+      "unit": "seconds"
+    }
+  },
+  "availability": {
+    "uptime-guarantee": 99.9
+  },
+  "data-integrity": {
+    "message-reliability": "atLeastOnce",
+    "loss-tolerance": 0
+  },
+  "error-handling": {
+    "retry-logic": {
+      "max-retries": 3,
+      "retry-interval": {
+        "value": 10,
+        "unit": "seconds"
+      }
+    }
+  },
+  "monitoring": {
+    "real-time-monitoring": "Use of monitoring tools like Prometheus or Grafana for SLA tracking.",
+    "consumer-reporting": {
+      "value": 1,
+      "unit": "days"
+    }
+  },
+  "incident-response": {
+    "incident-resolution-time": {
+      "value": 30,
+      "unit": "minutes"
+    },
+    "escalation-protocols": {
+      "incident-start-time-post-alert": {
+        "value": 5,
+        "unit": "minutes"
+      },
+      "escalation-path": "Notify the incident response team via the dedicated Slack channel."
+    }
+  },
+  "review-adjustments": {
+    "sla-review": {
+      "value": 1,
+      "unit": "months"
+    }
+  }
+}
diff --git a/calm/samples/traderx/flows/add-update-account/add-update-account.json b/calm/samples/traderx/flows/add-update-account/add-update-account.json
@@ -0,0 +1,36 @@
+{
+  "$schema": "https://calm.finos.org/draft/2024-10/meta/flow.json",
+  "$id": "https://calm.finos.org/traderx/flows/add-update-account.json",
+  "unique-id": "flow-add-update-account",
+  "name": "Add or Update Account",
+  "description": "Flow for adding or updating account information in the database.",
+  "transitions": [
+    {
+      "relationship-unique-id": "web-gui-process-uses-accounts-service",
+      "sequence-number": 1,
+      "summary": "Submit Account Create/Update"
+    },
+    {
+      "relationship-unique-id": "accounts-service-uses-traderx-db-for-accounts",
+      "sequence-number": 2,
+      "summary": "inserts or updates account"
+    },
+    {
+      "relationship-unique-id": "web-gui-process-uses-accounts-service",
+      "sequence-number": 3,
+      "summary": "Returns Account Create/Update Response Status",
+      "direction": "destination-to-source"
+    }
+  ],
+  "controls": {
+    "add-update-account-sla": {
+      "description": "Control requirement for flow SLA",
+      "requirements": [
+        {
+          "control-requirement": "https://calm.finos.org/traderx/controls/flow-sla-control-requirement.json",
+          "control-config": "https://calm.finos.org/traderx/flows/add-update-account/add-update-account-control-configuration.json"
+        }
+      ]
+    }
+  }
+}