Core Concepts

Understand the fundamental building blocks of Cascade Platform.

CDL: Cascade Definition Language

What is it? A YAML-based language for defining applications declaratively.

Why YAML?

Human-readable and easy to learn
Version-controllable (works great in Git)
IDE-friendly (syntax highlighting, validation)
Language-agnostic (use any backend)

Simple example:


workflows:
  - name: my_process
    start: InitialState
    states:
      - name: InitialState
        type: Task
        next: FinalState
      - name: FinalState
        type: Task
        end: true

Applications

What: A container for all workflows, decisions, and configurations.

Structure:


apiVersion: cascade.io/v1
kind: Application
metadata:
  name: my-app
  namespace: production
spec:
  workflows:
    - name: workflow1
      # ...
    - name: workflow2
      # ...
  policies:
    - name: policy1
      # ...

Lifecycle:

Define - Write application YAML
Validate - Cascade checks syntax and references
Deploy - Cascade applies it to the platform
Execute - Create workflow instances
Monitor - View logs, traces, metrics

Workflows

What: A state machine defining a business process.

Properties:

name - Unique identifier (e.g., “leave_request_flow”)
start - First state to execute
states - List of states and transitions
description - Human-readable explanation

Example:


workflows:
  - name: approval_process
    description: "Document approval workflow"
    start: SubmitDocument
    states:
      - name: SubmitDocument
        type: HumanTask
        next: ReviewByManager
      - name: ReviewByManager
        type: HumanTask
        next: Complete
      - name: Complete
        type: Task
        end: true

States

What: Execution units within a workflow. Different types for different purposes.

State Types

Type	Purpose	Duration	Example
Task	Execute activity (Go code)	Seconds	Validate input, call API
Choice	Conditional branching (1-3 conditions)	`<1ms`	Route by amount
HumanTask	Wait for user input	Hours/Days	Approval form
Parallel	Multiple branches simultaneously	Varies	Send notifications
Wait	Time-based delay	Precise	Retry after 1 hour
Receive	Wait for external event	Indefinite	Webhook callback
EvaluatePolicy	Business rules evaluation	Variable	Check compliance

State Example


- name: ApprovalDecision
  type: Choice
  description: "Route based on amount"
  choices:
    - variable: $.input.amount
      numericGreaterThan: 10000
      next: ExecutiveApproval
    - default: ManagerApproval

State lifecycle:

Enter state
Execute logic (specific to state type)
Output result to $.state and $.context
Transition to next state (based on output)

Activities

What: Executable units of work. Your custom Go code.

Format:


// internal/activities/approve_leave.go
func ApproveLeave(ctx context.Context, params ApproveLeaveParams) (ApproveLeaveResult, error) {
    // Your business logic here
    // - Call databases
    // - Call external APIs
    // - Compute values
    // - Return results
    
    return ApproveLeaveResult{
        Approved: true,
        Timestamp: time.Now(),
    }, nil
}

Called from Task state:


- name: ApproveLeave
  type: Task
  resource: urn:cascade:activity:approve_leave
  parameters:
    employee_id: $.context.employee_id
    leave_days: $.state.days_requested
  resultPath: $.approval_result
  next: NotifyEmployee

Deterministic execution:

Activities are called with inputs → produce outputs
Idempotent (safe to retry)
Temporal handles retries automatically

Policies

What: Business rules that are evaluated, not executed. Used in EvaluatePolicy states.

Three policy engines:

1. OPA (Open Policy Agent)

Language: Rego
Performance: <5ms (embedded in process)
Use for: Medium complexity (5-20 rules)
Example: Approval routing, compliance checks


package leave_approval

default approval_type = "manager"

approval_type = "auto" {
  input.days <= 2
  input.department == "Engineering"
}

approval_type = "executive" {
  input.days > 10
}

2. DMN (Decision Model and Notation)

Language: Visual decision tables
Performance: 10-50ms (HTTP to Camunda)
Use for: Complex decisions, visual editing
Example: Loan approval with complex rules

3. WASM (WebAssembly)

Language: Any language that compiles to WASM
Performance: <1ms
Use for: Performance-critical policies
Status: Coming in future release

UIs (User Interfaces)

What: Schema-driven dynamic UIs generated from JSON Schema + x-ui-* hints.

How it works:

Define data structure in JSON Schema
Add x-ui-* hints for rendering
UI framework renders it (Appsmith, RJSF, etc.)
User fills form
Form data saved to workflow state

Example:


- name: LeaveRequestForm
  type: HumanTask
  ui:
    schema: urn:cascade:schema:leave_request_form
    target: appsmith

JSON Schema with UI hints:


{
  "type": "object",
  "properties": {
    "start_date": {
      "type": "string",
      "format": "date",
      "x-ui-type": "datepicker"
    },
    "reason": {
      "type": "string",
      "x-ui-type": "textarea",
      "x-ui-placeholder": "Why do you need leave?"
    }
  }
}

UI Frameworks:

Appsmith (Primary) - Forms, tables, charts, layouts
RJSF (Secondary) - Forms only, lightweight
ECharts - Data visualization
TanStack - Data tables

Execution Model

How CDL Becomes Running Workflows


┌─────────────────────────────────────────┐
│ 1. Your CDL Application (YAML)          │
│    - Workflows, policies, schemas       │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│ 2. CSL Interpreter                      │
│    - Validates syntax                   │
│    - Resolves references (URNs)         │
│    - Compiles to executable form        │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│ 3. Temporal Workflow Engine             │
│    - Starts workflow instance           │
│    - Manages state transitions          │
│    - Handles retries & failures         │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│ 4. Activity Execution                   │
│    - Calls your Go functions            │
│    - Database/API calls                 │
│    - Business logic                     │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│ 5. State Persistence                    │
│    - PostgreSQL stores data             │
│    - Redis caches hot data              │
│    - Durable execution                  │
└─────────────────────────────────────────┘

Data Flow Through Execution


┌──────────────────────────────────────────────────┐
│ Workflow Instance                                 │
├──────────────────────────────────────────────────┤
│ input:       Initial parameters from user        │
│ state:       Mutable data (changes per state)    │
│ context:    Immutable environment data           │
│ result:      Final output                        │
└──────────────────────────────────────────────────┘

Example data:


{
  "input": {
    "employee_id": "emp-123",
    "leave_type": "vacation"
  },
  "state": {
    "start_date": "2025-11-15",
    "end_date": "2025-11-20",
    "days_requested": 5,
    "manager_approved": true
  },
  "context": {
    "employee_name": "John Doe",
    "department": "Engineering",
    "vacation_balance": 15
  },
  "result": {
    "approval_status": "approved",
    "approved_by": "jane@company.com"
  }
}

Architecture: Hexagonal Pattern

What: Clean architecture pattern that decouples business logic from technology.

Components:

Kernel (Center)

Business logic that’s independent of infrastructure
CSL Interpreter, State Machine Engine
Technology-agnostic

Ports (Interfaces)

Contracts that the kernel provides to the outside world
Examples: UIRendererPort, PolicyPort, StoragePort

Adapters (Implementations)

Pluggable implementations of ports
Different technologies can be swapped
Examples: Appsmith for UI, OPA for policies, PostgreSQL for storage

Benefits:

Easy to test (swap real adapters with mocks)
Easy to extend (add new adapters)
Easy to switch technologies
Business logic remains stable

Key Differences from Traditional Systems

Aspect	Traditional	Cascade
Definition	Code-based	YAML-based (CDL)
State	In-memory	Persisted (PostgreSQL)
Durability	Manual retry logic	Built-in (Temporal)
Observability	Added after	Built-in (OpenTelemetry)
UI Generation	Manual forms	Schema-driven (JSON Schema)
Policies	Embedded in code	Separate policy files
Infrastructure	Tightly coupled	Pluggable (Ports/Adapters)

Decision Architecture

Cascade provides a multi-tier decision strategy, optimized for different scenarios:


Use Case              → State Type          → Latency      → Performance
─────────────────────────────────────────────────────────────────────────
Simple routing       → Choice              → `<0.1ms       → 100K/s`ec
5-20 rules          → OPA (Policy)        → `<5ms         → 20K/s`ec
Complex decisions   → DMN (Policy)        → 10-50ms      → 1K-2K/sec
Performance-critical → WASM (Future)      → `<1ms         → 1M+/s`ec

When to use each:

Choice - 1-3 conditions, simple routing
OPA - Medium complexity, versioned policies
DMN - Complex rules, business analyst editing
WASM - Performance-critical policies (future)

Next Steps

You now understand:

✅ CDL (YAML-based language)
✅ Applications (containers for workflows)
✅ Workflows (state machines)
✅ States (execution units)
✅ Activities (your code)
✅ Policies (business rules)
✅ UIs (schema-driven forms)
✅ Execution model (how it all works)
✅ Architecture (Hexagonal pattern)

Continue Learning

Architecture Overview - Deeper dive into system design
Workflow Development - Advanced patterns
Policy Authoring - Write OPA and DMN policies
Examples - Real-world working applications

Congratulations! You’ve completed the Getting Started guide. You’re ready to build real workflows! 🚀