Add docs for workflow resources

docs/concepts/developer-abstractions.md

@@ -32,37 +32,44 @@ A **Component** represents a deployable unit of software - the fundamental build
 Each component encapsulates a specific piece of functionality, whether it's a microservice handling business logic, a
 web application serving user interfaces, or a background job processing data.
 
-Components provide the connection between source code and running applications. They define how code is built, what
-resources it requires, and how it should be deployed. This abstraction allows developers to focus on application logic
-while the platform handles the complexities of containerization, orchestration, and lifecycle management.
-
-## Component Types
-
-OpenChoreo provides specialized component types that represent common application patterns, each with its own
-operational characteristics and platform integrations.
-
-### Service
-
-A **Service** component represents backend applications that expose APIs or handle business logic. Services are the
-workhorses of cloud-native applications, processing requests, managing data, and integrating with other systems. The
-platform understands that services need stable network identities, load balancing, and API management capabilities.
-
-Services can expose multiple protocols including HTTP, gRPC, and TCP, with the platform handling the appropriate 
-routing and load balancing for each protocol type.
-
-### WebApplication
-
-A **WebApplication** component represents frontend applications that serve user interfaces. These might be single-page
-applications, server-side rendered websites, or static content. The platform recognizes that web applications have
-different operational requirements than backend services and provides appropriate deployment patterns through the 
-WebApplicationClass.
-
-### ScheduledTask
-
-A **ScheduledTask** component represents batch jobs, cron jobs, and other time-based workloads. Unlike continuously
-running services, scheduled tasks execute at specific times or intervals, complete their work, and terminate. 
-ScheduledTasks are configured with cron expressions to define when they should run, and the platform handles the 
-scheduling through the ScheduledTaskClass and Kubernetes CronJob resources.
+Components use a **ComponentType** reference to determine their deployment characteristics. This reference follows the
+format `{workloadType}/{componentTypeName}`, such as `deployment/web-service` or `cronjob/data-processor`. This explicit
+typing allows platform engineers to define multiple variations of deployment patterns for the same workload type, each
+tuned for different use cases.
+
+The Component resource connects four essential elements:
+
+**ComponentType Reference** specifies which platform-defined template governs this component's deployment. The
+ComponentType defines the available configuration schema, resource templates, and allowed workflows. This separation
+of concerns means developers work with a simplified interface while platform engineers maintain control over
+infrastructure patterns.
+
+**Parameters** provide the component-specific configuration values that conform to the schema defined in the
+ComponentType. These values include both static parameters that remain consistent across environments and
+environment-overridable parameters that can be customized per environment through ComponentDeployment resources. The
+inline schema syntax from the ComponentType validates these values automatically, ensuring developers provide correct
+types and stay within defined constraints.
+
+**Traits** enable composition of additional capabilities into the component. Each trait instance adds specific
+functionality like persistent storage, caching, or monitoring. Traits can be instantiated multiple times with
+different configurations using unique instance names. For example, a component might attach multiple persistent volume
+traits for different storage needs, each with its own size, storage class, and mount configuration. Traits use the
+same schema-driven approach as ComponentTypes, with parameters and environment overrides that can be customized through
+ComponentDeployment resources.
+
+**Workflow Configuration** optionally specifies how to build the component from source code. This references a
+Workflow and provides the developer-configured schema values needed to execute builds. The workflow integration
+enables automated container image creation triggered by code changes or manual developer actions.
+
+The component abstraction thus becomes a declarative specification that combines:
+- A ComponentType that defines *how* to deploy
+- Parameters that configure *what* to deploy
+- Traits that compose *additional capabilities*
+- A Workflow that defines *how to build*
+
+This composition-based approach enables developers to assemble complex applications from reusable building blocks
+while the platform ensures consistency, governance, and operational best practices through the underlying ComponentType
+and Trait templates.
 
 ## Workload
 
@@ -88,16 +95,28 @@ enables platform teams to control infrastructure policies while developers focus
 limits, scaling parameters, and operational policies come from the ServiceClass or WebApplicationClass, while the 
 workload simply declares what the application needs to function.
 
-## Build
+## WorkflowRun
+
+A **WorkflowRun** represents a runtime execution instance of a Workflow. While Workflows define the template and schema
+for what can be executed, WorkflowRuns represent actual executions with specific parameter values and context.
+
+WorkflowRuns bridge the gap between developer intent and CI/CD execution. Developers create WorkflowRun resources to
+trigger workflows, providing only the schema values defined in the Workflow template. The platform handles all the
+complexity of rendering the final workflow specification, synchronizing secrets, and managing execution in the build
+plane.
 
-A **Build** represents the process of transforming source code into deployable artifacts. It captures the build
-configuration, tracks build execution, and manages the resulting container images. The build abstraction provides a
-consistent interface for different build strategies while handling the complexities of secure, reproducible builds.
+Each WorkflowRun captures two essential pieces of information:
 
-Builds in OpenChoreo are first-class resources that can be monitored, audited, and managed independently of deployments.
-This separation enables practices like building once and deploying many times, pre-building images for faster
-deployments, and maintaining clear traceability from source code to running containers.
+**Workflow Configuration** references the Workflow template to use and provides the developer-configured schema values.
+These values conform to the schema defined in the referenced Workflow, with automatic validation ensuring type
+correctness and constraint satisfaction. For example, a Docker build workflow might receive repository URL, branch
+name, and Dockerfile path, while a buildpack workflow might receive additional configuration for build resources,
+caching, and testing modes.
 
-The platform supports multiple build strategies to accommodate different technology stacks and organizational
-preferences. Whether using Cloud Native Buildpacks for automatic, opinionated builds or custom Dockerfiles for complete
-control, the build abstraction provides a consistent operational model.
+This abstraction provides a simplified interface where developers interact with curated schemas rather than complex
+CI/CD pipeline definitions, while creating permanent audit trails essential for compliance and debugging. The separation
+of concerns allows platform engineers to control workflow implementation and security policies through Workflow templates
+while developers manage application-specific parameters through WorkflowRun schema values. For component-bound workflows,
+automatic linkage between builds and components enables coordinated build and deployment lifecycles. WorkflowRuns can be
+created manually for ad-hoc builds or automatically by platform controllers in response to code changes, supporting both
+interactive development and fully automated CI/CD pipelines while maintaining consistent execution patterns and governance.

docs/concepts/platform-abstractions.md

@@ -108,35 +108,99 @@ configured for sensitive environments, automated testing can be triggered at pro
 can be enforced before production deployment. This ensures that all applications follow organizational standards
 regardless of which team develops them.
 
-## Class System
-
-OpenChoreo implements the standard Kubernetes Class pattern, similar to GatewayClass or StorageClass, enabling platform
-engineers to define platform-level abstractions that developers consume through their applications.
-
-### The Class Pattern
-
-Classes are platform-level resources that encode organizational standards, best practices, and governance policies.
-Platform engineers create Classes for different workload types - ServiceClass for backend services, WebApplicationClass
-for frontend applications, and ScheduledTaskClass for batch jobs. Each Class defines the platform standards that
-applications must follow when claiming these resources.
-
-Just as GatewayClass defines infrastructure capabilities that Gateway resources consume, or StorageClass defines how
-storage should be provisioned when a PersistentVolumeClaim is created, ServiceClass defines how services should be
-deployed when developers create Service resources. This pattern provides a clean separation between platform
-capabilities (defined by platform engineers) and application requirements (expressed by developers).
-
-### Class Consumption
-
-When developers create application resources like Service or WebApplication, they reference the appropriate Class,
-similar to how a PersistentVolumeClaim references a StorageClass. The platform uses the Class definition to provision
-the actual workload with the correct configuration, policies, and governance rules.
-
-Environment-specific Bindings act as the instantiation of this claim in a specific environment. While the Service
-resource expresses the developer's intent and references a ServiceClass, the ServiceBinding represents the actual
-deployment of that service in a particular environment with environment-specific overrides.
-
-This consumption model balances standardization with flexibility. Platform teams maintain control over critical
-configurations through Classes while developers express their requirements through simple resource definitions. The
-platform handles the complex mapping between developer intent and infrastructure reality.
-
-
+## Component Types
+
+A **ComponentType** is a platform engineer-defined template that governs how components are deployed and managed in
+OpenChoreo. It represents the bridge between developer intent and platform governance, encoding organizational
+policies, best practices, and infrastructure patterns as reusable templates.
+
+ComponentTypes implement the platform's claim/class pattern at the component level. While developers create Components
+that express their application requirements, platform engineers define ComponentTypes that specify how those
+requirements should be fulfilled. This separation enables developers to focus on application logic while platform
+engineers maintain control over infrastructure policies, resource limits, security configurations, and operational
+standards.
+
+Each ComponentType is built around a specific **workload type** - the primary Kubernetes resource that will run the
+application. OpenChoreo supports four fundamental workload types:
+
+- **deployment**: For long-running services that need continuous availability
+- **statefulset**: For applications requiring stable network identities and persistent storage
+- **cronjob**: For scheduled tasks that run at specific times or intervals
+- **job**: For one-time or on-demand batch processing tasks
+
+The ComponentType uses a **schema-driven architecture** that defines what developers can configure when creating
+components. This schema consists of two types of parameters:
+
+**Parameters** are static configurations that remain consistent across all environments. These include settings like
+replica counts, image pull policies, and container ports. Once set at component creation, these values apply uniformly
+whether the component runs in development, staging, or production.
+
+**EnvOverrides** are configurations that platform engineers can override on a per-environment basis through
+ComponentDeployment resources. These typically include resource allocations, scaling limits, and environment-specific
+policies. This flexibility allows platform engineers to provide generous resources in production while constraining
+development environments to optimize infrastructure costs.
+
+The schema uses an inline type definition syntax that makes configuration requirements explicit and self-documenting.
+For example, `"integer | default=1"` declares an integer parameter with a default value, while
+`"string | enum=Always,IfNotPresent,Never"` restricts a string to specific allowed values. This syntax supports
+validation rules like minimum/maximum values, required fields, and enumerated choices.
+
+ComponentTypes define **resource templates** that generate the actual Kubernetes resources for components. Each
+template uses CEL (Common Expression Language) expressions to dynamically generate resource manifests based on
+component specifications. Templates can access component metadata, schema parameters, and workload specifications
+through predefined variables like `${metadata.name}` and  `${parameters.replicas}`.
+
+Templates support advanced patterns through conditional inclusion and iteration. The `includeWhen` field uses CEL
+expressions to conditionally create resources based on configuration, enabling optional features like autoscaling or
+ingress. The `forEach` field generates multiple resources from lists, useful for creating ConfigMaps from multiple
+configuration files or managing multiple service dependencies.
+
+ComponentTypes can also restrict which **Workflows** developers can use for building components through the
+`allowedWorkflows` field. This enables platform engineers to enforce build standards, ensure security scanning, or
+mandate specific build tools for different component types. For instance, a web application ComponentType might only
+allow Workflows that use approved frontend build tools and security scanners.
+
+This schema-driven approach ensures consistency across the platform while providing flexibility for different
+application patterns. Platform engineers create ComponentTypes that encode organizational knowledge about how to run
+applications securely and efficiently, while developers benefit from simplified configuration and automatic compliance
+with platform standards.
+
+## Workflows
+
+A **Workflow** is a platform engineer-defined template for executing build, test, and automation tasks in OpenChoreo.
+Workflows provide a schema-driven interface that separates developer-facing parameters from platform-controlled
+configurations, enabling developers to trigger complex CI/CD processes through simple, validated inputs.
+
+Workflows in OpenChoreo integrate with Argo Workflows to provide Kubernetes-native execution for continuous
+integration tasks. Unlike traditional CI/CD systems where developers must understand pipeline implementation details,
+OpenChoreo Workflows present a curated schema of configurable options while platform engineers control the underlying
+execution logic, security policies, and infrastructure configurations.
+
+Each Workflow defines a **schema** that specifies what developers can configure when creating a run instance.
+This schema uses the same inline type definition syntax as ComponentTypes, making validation rules explicit and
+self-documenting. The schema typically includes repository configuration, build parameters, resource limits, and
+testing options, with type validation, default values, and constraints enforced automatically.
+
+The Workflow's **resource template** contains the actual Argo Workflow specification with CEL expressions for dynamic
+value injection. These expressions access three categories of variables:
+
+**Context variables** (`${ctx.*}`) provide runtime information like the workflow run name, component name, project name, and
+organization name. These enable unique resource naming and proper isolation across
+executions.
+
+**Schema variables** (`${schema.*}`) inject developer-provided values from the WorkflowRun instance. These include
+repository URLs, build configurations, and other parameters defined in the workflow schema.
+
+**Platform-controlled parameters** are hardcoded directly in the workflow and remain invisible to developers. These may
+include container image references, registry URLs, security scanning configurations, and organizational policies. By
+hardcoding these values, platform engineers ensure compliance with security standards and infrastructure policies
+regardless of developer input.
+
+Workflows can be referenced by Components through the `workflow` field, enabling automated builds triggered by code
+changes or manual developer actions. ComponentTypes can restrict which Workflows are allowed through the
+`allowedWorkflows` field, ensuring that different component types use appropriate build strategies and security
+policies.
+
+The Workflow abstraction thus provides a controlled interface to powerful CI/CD capabilities, enabling platform teams
+to offer self-service build automation while maintaining governance over build processes, security scanning, artifact
+storage, and compliance requirements.