PRD: Elsa Deployment Platform

## Decision

Store this PRD directly in the GitHub issue for now.

Reasoning: this is still a draft product direction with multiple deferred architectural decisions. Keeping it as an issue makes the PRD discoverable, discussable, and easy to refine before promoting it into a committed `specs/` implementation plan or ADR. Once the scope is accepted, follow-up issues or a dedicated spec can reference this issue as the source product brief.

## Review Summary

The PRD is directionally strong and appropriately platform-oriented. It clearly separates deployment/control-plane state from runtime/data-plane state, which is the most important architectural boundary for avoiding unsafe reconciliation behavior.

Key refinements applied in this issue body:

- Converted the PRD into GitHub-flavored Markdown.
- Preserved the original product intent and roadmap.
- Made deferred decisions explicit rather than implying premature certainty.
- Added acceptance criteria for using this issue as the product-level tracking item.
- Kept implementation details high-level so follow-up specs can decompose the work safely.

Recommended next decisions before implementation planning:

- Define the first supported deployment resource taxonomy.
- Choose the Phase 1 reconciliation hosting model and API surface.
- Define artifact identity, versioning, and signing boundaries.
- Decide whether Phase 1 drift handling is strict, advisory, or resource-specific.
- Define how partial deployment failure is represented, resumed, and audited.

## Acceptance Criteria For This Issue

- [ ] Product direction for the Elsa Deployment Platform is reviewed and accepted or revised.
- [ ] Phase 1 scope is converted into implementation issues or a formal `specs/` feature plan.
- [ ] Deferred architecture decisions are either resolved or captured as separate decision records.
- [ ] Follow-up work references this issue as the originating PRD.

---

# Elsa Deployment Platform PRD

## Status

Draft

## Vision

Create a portable, extensible, declarative deployment platform for Elsa-based systems that enables teams to safely package, promote, reconcile, and govern workflows and runtime configuration across environments.

The platform should support:

- Small self-hosted deployments
- Enterprise CI/CD pipelines
- GitOps workflows
- Multi-tenant SaaS environments
- Air-gapped installations
- Runtime modularity
- Declarative environment composition
- Future platform engineering scenarios

The deployment story must remain:

- Transport-agnostic
- Environment-agnostic
- Hosting-model agnostic
- API-first
- Portable
- Extensible

## Problem Statement

Teams adopting Elsa quickly encounter operational complexity:

- Workflows are authored dynamically
- Environments drift over time
- Workflows must be promoted safely
- Deployments require auditability
- Runtime configuration varies per environment
- Workflows depend on packages and features
- CI/CD pipelines require deterministic deployments
- Operators require rollback and validation capabilities

Current approaches based on importing workflow JSON, copying databases, or manually synchronizing environments do not scale operationally.

Elsa needs a first-class deployment platform.

## Goals

### Primary Goals

- Declarative environment composition
- Deterministic deployments
- Immutable deployment artifacts
- Safe workflow promotion
- GitOps compatibility
- Multi-environment portability
- API-first deployment architecture
- Modular runtime composition
- Extensible deployment resource model
- Drift detection capabilities
- Enterprise-grade governance and auditability

### Secondary Goals

- Air-gapped deployment support
- OCI artifact compatibility
- Multi-tenant environment layering
- Reconciliation-based convergence
- Runtime self-healing
- Policy-driven deployment validation
- Hosted deployment experiences

## Non-Goals

The following are explicitly out of scope for initial versions:

- Workflow instance migration
- Runtime state reconciliation
- Cross-version workflow instance replay
- Custom secret management implementation
- Kubernetes-only deployment support
- Reconciliation of transient execution state
- Automatic workflow semantic merging
- Distributed transaction guarantees across all deployment resources
- Full infrastructure provisioning, such as replacing Terraform

## Architectural Principles

### Declarative Desired State

Deployments describe desired runtime state rather than imperative mutation steps.

### Immutable Deployment Artifacts

Deployment artifacts are versioned and immutable.

### Runtime And Deployment Separation

Deployment state and runtime execution state remain strictly separated.

### API-First Architecture

All deployment operations should be available through stable APIs.

### Portable Deployments

Deployments must work across:

- Docker Compose
- Kubernetes
- Bare metal
- Cloud-hosted environments
- Hybrid environments

### Idempotent Reconciliation

Repeated deployment application should converge toward desired state safely.

### Transport Agnostic

Deployment transport mechanisms must remain pluggable.

### GitOps Compatibility

Deployment resources should serialize cleanly into Git-friendly formats.

### Extensible Resource Model

Third parties should be able to contribute new deployable resource types.

## Conceptual Model

### Control Plane Vs Data Plane

#### Control Plane State

Declarative environment state:

- Workflow definitions
- Packages
- Features
- Schedules
- Variables
- Permissions
- Recipes
- Secret references

#### Data Plane State

Runtime execution state:

- Workflow instances
- Bookmarks
- Activity execution state
- Execution logs
- Distributed locks
- Runtime queues

The deployment platform must not reconcile data plane state.

## Core Concepts

### Environment Manifest

Declarative description of desired runtime state.

Example:

```yaml
apiVersion: elsa.io/v1
kind: EnvironmentManifest
packages:
- id: Acme.Sales
version: 1.4.2
features:
- sales
- sap
recipes:
- initialize-sales
workflows:
- order-approval
variables:
orderTimeout: 30
```

### Deployment Artifact

Immutable deployment unit.

Possible formats:

- ZIP bundle
- OCI artifact
- NuGet package
- Recipe package

Contains:

- Manifests
- Workflows
- Recipes
- Metadata
- Signatures
- Version information

### Reconciliation

Process that converges actual runtime state toward desired state.

Potential hosting models:

- Embedded runtime reconciler
- External operator service
- CLI-driven reconciliation
- GitOps reconciliation agent

### Resource

Deployable unit managed declaratively.

Examples:

- Workflow
- Package
- Feature
- SecretReference
- Variable
- Schedule
- Permission
- Recipe
- Endpoint
- Connection

Future versions may leverage Aster resource abstractions.

## Deployment Architecture

### Core Components

#### `Elsa.Deployment.Abstractions`

Shared deployment contracts and interfaces.

#### `Elsa.Deployment.Engine`

Host-agnostic reconciliation engine.

#### `Elsa.Deployment.Api`

Deployment APIs.

#### `Elsa.Deployment.HostedService`

Embedded in-process reconciler.

#### `Elsa.Deployment.Operator`

External reconciliation/operator service.

#### `Elsa.Deployment.Cli`

CLI tooling for CI/CD and local operations.

#### `Elsa.Deployment.GitOps`

Optional GitOps integration components.

## Deployment Flows

### Developer-Driven Promotion

```text
DEV
-> Commit deployment artifact
-> PR review
-> CI validation
-> Staging deployment
-> Approval gate
-> Production deployment
```

### GitOps Flow

```text
Git push
-> GitOps watcher detects changes
-> Reconciliation triggered
-> Runtime converges toward desired state
```

### UI-Driven Promotion

```text
User promotes deployment
-> Immutable deployment bundle created
-> Deployment workflow executes
-> Environment reconciles
```

### Air-Gapped Deployment

```text
Signed deployment bundle
-> Offline transfer
-> Local reconciliation
-> Validation + deployment
```

## Workflow Deployment Model

### Workflow Identity

Recommended model:

- Workflow ID: stable logical identity
- Workflow Version ID: immutable version identity

Example:

```text
order-approval
version 12
```

### Workflow Versioning

Recommended approach:

- Immutable workflow versions
- Activation determines active version
- Rollback reactivates previous versions

Avoid mutable in-place workflow editing across environments.

## Secrets Strategy

The deployment platform should manage:

- Secret references
- Secret bindings

The platform should not:

- Store raw secrets
- Export secrets

Supported providers may include:

- Azure Key Vault
- AWS Secrets Manager
- HashiCorp Vault
- Kubernetes Secrets
- Environment variables

Example:

```yaml
secrets:
sapApiKey:
provider: vault
key: production/sap/key
```

## Environment Layering

The platform should support layered configuration.

Example:

```text
base/
staging/
production/
tenant-overrides/
```

Potential strategies:

- Overlays
- Inheritance
- Parameterization
- Variable substitution

## Drift Detection

Potential models:

### Strict Reconciliation

Actual state forcibly matches desired state.

### Advisory Reconciliation

Drift is detected but not automatically corrected.

### Hybrid Reconciliation

Some resources are strictly reconciled, while others are advisory.

Decision deferred.

## Validation And Safety

Required capabilities:

- Dry-run mode
- Deployment preview
- Diff visualization
- Dependency validation
- Compatibility checks
- Resumable deployments
- Idempotent execution
- Deployment history
- Rollback support

## Compatibility Validation

The platform should validate the following before deployment execution:

- Required packages
- Required activities
- Feature compatibility
- Schema compatibility
- Environment compatibility

## Loom Integration

Loom recipes may serve as:

- Environment mutation units
- Initialization steps
- Deployment operations
- Upgrade operations

Examples:

- Install package
- Enable feature
- Seed users
- Import workflows
- Configure permissions

Loom should remain independent from reconciliation mechanics.

## Nuplane Integration

Nuplane may provide:

- Runtime package distribution
- Package resolution
- Package installation
- Runtime module loading

## CShells Integration

CShells may provide:

- Runtime modular composition
- Feature activation
- Runtime capability isolation
- Tenant-specific feature composition

## Aster Integration Future

Potential future role:

- Typed deployable resource abstractions
- Extensible application resource modeling
- Third-party resource type extensibility

Aster should remain independent from deployment mechanics.

## Multi-Tenancy

The platform should eventually support:

- Tenant-scoped manifests
- Layered tenant overrides
- Tenant-specific deployments
- Shared or global resources
- Isolated reconciliation

Potential layering model:

```text
platform
-> environment
-> tenant
```

## API Requirements

The deployment platform should expose APIs for:

- Deployment execution
- Deployment history
- Reconciliation status
- Package management
- Workflow management
- Recipe execution
- Environment manifests
- Validation
- Drift detection

## Governance And Auditability

Required concepts:

- Deployment
- Deployment Revision
- Deployment Approval
- Deployment History
- Deployment Status

Potential future capabilities:

- Signed manifests
- Policy enforcement
- Deployment attestations

## Open Questions

### Reconciliation Hosting

Should reconciliation occur in-process, externally, or both?

Current recommendation: both.

### Drift Philosophy

Should deployments enforce state strictly, allow manual divergence, or selectively reconcile resources?

Deferred.

### Workflow Mutability

Should workflows be immutable across deployments or mutable in-place?

Recommendation: immutable versions.

### Deployment Transactions

How should partial deployment failure behave?

Questions:

- Roll back automatically?
- Resume later?
- Allow partial convergence?

Deferred.

### Resource Taxonomy

What should constitute first-class deployable resources?

Deferred pending broader platform evolution.

### Environment Overlay Model

Should overlays resemble Helm, Kustomize, Terraform variables, or a custom layering model?

Deferred.

## Roadmap

### Phase 1: Foundational Deployment Platform

Goals:

- Establish deployment primitives
- Support deterministic deployments
- Support CI/CD usage

Deliverables:

- Environment manifests
- Deployment artifacts
- Embedded reconciler
- Deployment APIs
- CLI tooling
- Loom recipe execution
- Workflow deployment
- Package deployment
- Deployment history
- Dry-run mode
- Validation pipeline

### Phase 2: Enterprise Deployment Capabilities

Goals:

- Improve governance
- Improve operational maturity

Deliverables:

- External operator service
- Drift detection
- OCI artifact support
- Signed artifacts
- Approval workflows
- Environment overlays
- Secret references
- Multi-environment promotion
- GitOps integration

### Phase 3: Platform Engineering Expansion

Goals:

- Large-scale orchestration
- Fleet management
- Advanced reconciliation

Deliverables:

- Multi-tenant reconciliation
- Kubernetes CRDs
- Advanced overlays
- Progressive rollout support
- Fleet management
- Policy engine
- Deployment attestations
- Distributed reconciliation

## Long-Term Vision

The long-term direction is not merely workflow deployment.

The platform evolves toward:

```text
Declarative Runtime Composition
+
Workflow Deployment
+
Application Resource Management
+
Platform Engineering
+
Operational Governance
```

This positions Elsa as:

- A workflow orchestration platform
- A modular runtime platform
- A deployable application composition platform
- A GitOps-compatible operational platform
- A foundation for hosted workflow infrastructure ecosystems