Update content

Author: markdembo

src/content/docs/reference-architecture/diagrams/serverless/programmable-platforms.mdx

@@ -2,91 +2,93 @@
 title: Programmable Platforms
 pcx_content_type: reference-architecture-diagram
 products:
-  - Workers
-  - KV
+   - Workers
+   - KV
 sidebar:
-  order: 1
-  label: Programmable Platforms
-updated: 2025-03-12
+   order: 1
+   label: Programmable Platforms
+updated: 2025-03-16
 ---
 
 
 ## Introduction
 
-A programmable platform is a software ecosystem that enables customers to extend and customize core functionality through code. Unlike traditional SaaS offerings with fixed features, programmable platforms empower customers to build bespoke solutions within the platform's infrastructure, creating unique experiences while leveraging the platform's core capabilities.
+A programmable platform is a software ecosystem that enables customers to extend and customize core functionality through code. Unlike traditional SaaS offerings with fixed features, programmable platforms empower customers to build tailored solutions within the platform’s infrastructure, creating unique experiences while leveraging the platform’s core capabilities. These platforms enable a high degree of customization, allowing users to deploy their own backend logic, host frontend applications, or even run full-stack experiences - all within the provider’s infrastructure.
+
+Hosting the infrastructure for these platforms presents several challenges, including security, scalability, cost efficiency, and performance isolation. Allowing customers to run custom code introduces risks such as untrusted execution, potential abuse, and resource contention, all of which must be managed without compromising platform reliability. Running millions of single-tenant applications is inherently costly, making efficient resource utilization critical. The ability to scale workloads to zero when idle is key to ensuring economic viability while maintaining rapid startup times when demand spikes. Additionally, ensuring seamless global execution with low-latency performance requires a resilient, distributed architecture. Robust monitoring, debugging, and governance capabilities are also essential to provide visibility and control over customer-deployed code without restricting innovation.
+
+[Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/) provides the ideal infrastructure for building programmable platforms by offering secure, isolated environments where customers can safely execute custom code at scale, with automatic scaling to zero and a globally distributed runtime that optimizes performance and cost.
 
-Cloudflare Workers for Platforms provides the ideal infrastructure for building programmable platforms by offering secure, isolated environments where customers can safely execute custom code without compromising the integrity or performance of the underlying platform.
 
 ## Core Architecture Components
 
-The Workers for Platforms architecture consists of several key components that work together to provide a secure, scalable, and efficient solution for multi-tenant applications:
+The Workers for Platforms architecture consists of several key components that work together to provide a secure, scalable, and efficient solution for multi-tenant applications. In the following core concepts are outlined.
 
-1. **Dynamic Dispatch Worker**: The entry point for client requests that routes traffic to the appropriate customer-specific worker based on request parameters.
+1. **Main Request Flow**: An overview over the a request flow in a programmable platform.
 
-2. **Dispatch Namespace**: A logical grouping of customer-specific workers that isolates resources and execution environments.
+2. **Invocation & Metadata Flow**: commonly, incoming requests and enriched with metadata to provide the function invocation with relevant context or perform routing logic.
 
-3. **User Workers**: Customer-specific workers that process isolated workloads within their own secure execution context.
+3. **Egress Control**: controlling outbound connections to ensure compliant behaviour.
 
-4. **Storage & Data Resources**: Various data storage options (D1, KV, R2, Durable Objects) that can be isolated per customer.
+4. **Utilizing Storage & Data Resources**: leveraging databases & storage to build even richer end-user expierences at scale.
 
 5. **Observability Tools**: Logging and metrics collection services to monitor platform performance and troubleshoot issues.
 
 ## Main Request Flow
 
-![Figure 2: Workers for Platforms: Invocation & Metadata](~/assets/images/reference-architecture/programmable-platforms/programmable-platforms-1.svg "Figure 2: Workers for Platforms: Invocation & Metadata")
+![Figure 1: Workers for Platforms: Main Flow](~/assets/images/reference-architecture/programmable-platforms/programmable-platforms-1.svg "Figure 1: Workers for Platforms: Main Flow")
 
 
-1. **Client Request**: A request is sent from a client application to the platform's Dynamic Dispatch Worker.
+1. **Client Request**: Send request from a client application to the platform's [Dynamic Dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker).
 
-2. **Tenant Identification & Routing**: The Dynamic Dispatch Worker identifies the appropriate customer environment using `env.namespace.get(customer-id)` and routes the request to the corresponding User Worker within the Dispatch Namespace.
+2. **Routing**: Identify the correct workload to execute and route the request to the respective [User Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers) in the [Dispatch Namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace). Each customer's workload runs in an isolated User Worker with its own resources and security boundaries.
 
-3. **Isolated Execution**: Each customer's workload runs in an isolated User Worker with its own resources and security boundaries.
 
 ## Invocation & Metadata Flow
 
 ![Figure 2: Workers for Platforms: Main Flow](~/assets/images/reference-architecture/programmable-platforms/programmable-platforms-2.svg "Figure 2: Workers for Platforms: Main Flow")
 
+For many use cases, it makes sense to retrieve additional metadata, user data, or configuration to process incoming requests and provide the User Worker invocation with additional context.
 
+1. **Incoming Request**: Send requests to custom hostnames or a Worker using a Workers wildcard route.
 
-1. **Request Routing**: Client requests are directed based on hostname or path patterns:
-   - Custom hostnames for specific customers 
-   - Routing within a shared domain (hostname or path-based)
+2. **Metadata Lookup**: Retrieve customer-specific configuration data from [KV](/kv/) storage. These lookups are typically based on the hostname of the incoming request or custom metadata in the case of custom hostnames.
 
-2. **Metadata Lookup**: The Dynamic Dispatch Worker may interact with KV storage to retrieve customer-specific configuration data.
-
-3. **Worker Invocation**: Based on the retrieved metadata, requests are routed to the appropriate User Worker in the Dispatch Namespace.
+3. **Worker Invocation**: Route requests to the appropriate User Worker in the Dispatch Namespace based on metadata. Optionally, provide additional context during function invocation.
 
 ## Egress Control Pattern
 
 ![Figure 3: Workers for Platforms: Egress Control](~/assets/images/reference-architecture/programmable-platforms/programmable-platforms-3.svg "Figure 3: Workers for Platforms: Egress Control")
 
+Data observability and control is crucial for security. [Outbound Workers](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/) allow for interception of all outgoing requests in User Worker scripts. 
+
+1. **Worker Invocation**: Route requests to the appropriate User Worker in the Dispatch Namespace. Optionally pass additional parameters to the Outbound Worker during User Worker invocation.
 
-1. **Internal Routing**: The Dynamic Dispatch Worker routes requests to the appropriate User Worker within the Dispatch Namespace.
+2. **External requests**: Send requests via `fetch()` calls to external services through a controlled Outbound Worker.
 
-2. **Controlled External Access**: User Workers can make `fetch()` calls to external services through a controlled Outbound Worker.
+3. **Request interception**: Evaluate outgoing requests and perform core functions like centralized policy enforcement and audit logging.
 
-3. **External Service Integration**: The Outbound Worker provides a standardized interface for communicating with external services, allowing for centralized policy enforcement, rate limiting, and audit logging.
 
 ## Metrics & Logging Architecture
 
 ![Figure 4: Workers for Platforms: Metrics & Logging](~/assets/images/reference-architecture/programmable-platforms/programmable-platforms-4.svg "Figure 4: Workers for Platforms: Metrics & Logging")
 
 
-1. **Comprehensive Logging**: All Workers in the request flow can send logs to Tail Worker and Logpush services.
+1. **Logging**: Collect logs throughout all Workers in the request flow via [Tail Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/observability/#tail-workers) and [Workers Trace Events Logpush](/workers-for-platforms/configuration/observability/#workers-trace-events-logpush) services.
 
-2. **Metrics Collection**: Performance and usage metrics are captured through Analytics Engine and exposed via GraphQL.
+2. **Metrics**: Collect custom metrics via [Workers Analytics Engine](/analytics/analytics-engine/) and out-of-the-box [Analytics](/analytics/graphql-api/) that can readily be queried via GraphQL API.
 
-3. **Third-party Integration**: Logs and metrics can be exported to various external monitoring and analytics platforms like Datadog, Splunk, Grafana, and others.
+3. **Third-party Integration**: Export logs and metrics to various external monitoring and analytics platforms like Datadog, Splunk, Grafana, and others via [Analytics integrations](/analytics/analytics-integrations/).
 
 ## Resource Isolation Model
 
 ![Figure 5: Workers for Platforms: Resources](~/assets/images/reference-architecture/programmable-platforms/programmable-platforms-5.svg "Figure 5: Workers for Platforms: Resources")
 
-1. **Client Request**: Requests are routed through the Dynamic Dispatch Worker.
+1. **Incoming Request**: Send requests to custom hostnames or a Worker using a Workers wildcard route.
 
-2. **Customer Identification**: The Dynamic Dispatch Worker identifies the appropriate customer environment.
+2. **Worker Invocation**: Route requests to the appropriate User Worker in the Dispatch Namespace.
 
-3. **Resource Access**: Each User Worker has access only to its customer-specific resources:
+3. **Resource Access**: Interact with per-script-specific resources:
    - D1 for relational database storage
    - Durable Objects for strongly consistent data
    - KV for high-read, eventually consistent key-value storage
@@ -97,16 +99,14 @@ The Workers for Platforms architecture consists of several key components that w
 ![Figure 6: Workers for Platforms: Deployment & Management Flow](~/assets/images/reference-architecture/programmable-platforms/programmable-platforms-6.svg "Figure 6: Workers for Platforms: Deployment & Management Flow")
 
 
-1. **Management Interface**: End users interact with the platform through GUI, API, or CLI interfaces.
+1. **Management Interface**: Interact with the platform through GUI, API, or CLI interfaces.
 
-2. **Platform Processing**: The SaaS provider processes these interactions to:
+2. **Platform Processing**: Process these interactions to:
    - Transform and bundle code
    - Perform security checks
    - Apply configuration
 
-3. **API Deployment**: The processed workloads are deployed to the Dispatch Namespace via the Cloudflare REST API.
-
-
+3. **Change Management**: Deploy changes to Cloudflare using the Cloudflare REST API.
 
 
 ## Conclusion
@@ -118,3 +118,4 @@ Cloudflare Workers for Platforms provides a robust foundation for building multi
 - [Workers for Platforms: Get started](cloudflare-for-platforms/workers-for-platforms/get-started/)
 - [Workers for Platforms: Outbound Workers](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/)
 - [Workers for Platforms: Observability](/cloudflare-for-platforms/workers-for-platforms/configuration/observability/)
+