name: architect description: This skill designs industry-grade Cloudflare architectures with wrangler.toml generation, Mermaid diagrams, and Edge-Native Constraint validation. Use this skill when the user asks about "designing new systems", "planning migrations", "evaluating architecture options", or mentions "Node.js libraries" that may not work on Workers.

Cloudflare Architect Skill

Design production-ready Cloudflare architectures with proper service selection, wrangler configuration generation, visual diagrams, and Edge-Native Constraint enforcement.

Core Capabilities

1. Architecture Design - Service selection, data flow, scalability/cost trade-offs
2. Configuration Generation - Complete wrangler.toml/jsonc with all bindings
3. Visual Documentation - Mermaid diagrams for architecture and data flow
4. Edge-Native Validation - Cross-reference code against Workers runtime compatibility
5. Workers + Assets - Unified Worker with [assets] block for frontend + API

Service Selection Matrix

Storage Selection

Compute Selection

AI/ML Selection

Workload Router

Select the right compute model:

• Workers (Isolates): Standard APIs, database CRUD, AI inference via Workers AI
• Python Workers: Pure Python scripts, AI SDKs (limited packages)
• Containers (Beta): FFmpeg, Puppeteer, numpy/pandas, long-running processes

See: references/workload-router.md for decision trees and compatibility tables.

Edge-Native Constraints

Workers use V8 isolates, NOT Node.js. Key incompatibilities:

See: references/edge-constraints.md for full compatibility tables.

Workers + Assets (Replaces Pages)

For fullstack apps, use unified Worker with [assets] block:

{
  "name": "fullstack-app",
  "main": "src/worker.ts",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "single-page-application"
  }
}

See: references/workers-assets.md for migration from legacy [site] and Pages.

Wrangler Health Check

Before designing, verify wrangler version:

npx wrangler --version

Design Workflow

Step 1: Requirements Gathering

Ask about:

1. Traffic patterns: Requests/second, geographic distribution
2. Data characteristics: Size, structure, access patterns
3. Processing needs: Sync vs async, latency requirements
4. Budget constraints: Target monthly cost
5. Compliance: Data residency, encryption requirements

Step 2: Service Selection

For each requirement, select appropriate service using the matrices above.

Step 3: Architecture Draft

Create Mermaid diagram showing:

• All Workers and their responsibilities
• Storage bindings and data flow
• Queue topology (if async processing)
• External service integrations

See: references/architecture-templates.md for pre-built templates.

Step 4: Configuration Generation

Generate wrangler.jsonc with:

• All bindings properly named
• Environment-specific overrides
• Proper placement mode
• Observability enabled
• Queue DLQs configured

Step 5: Cost Estimation

Calculate monthly costs using service rates from the selection matrices.

Step 6: Review Checklist

Before finalizing:

• All queues have DLQs
• D1 has appropriate indexes planned
• Smart placement enabled for latency-sensitive
• Observability configured
• Secrets use wrangler secret (not vars)
• Rate limiting for public APIs
• limits.cpu_ms set appropriately

Billing Safety Limits

CRITICAL: Set CPU limits to prevent runaway loops:

{
  "limits": {
    "cpu_ms": 100  // Kill execution if CPU churns >100ms
  }
}

See: references/billing-safety.md for anti-patterns and protection strategies.

Output Format

When designing an architecture, provide:

1. Requirements Summary - Confirmed requirements
2. Architecture Diagram - Mermaid visualization
3. Service Justification - Why each service was chosen
4. Wrangler Configuration - Complete, deployable config
5. Cost Estimate - Monthly projection with breakdown
6. Migration Path - If replacing existing system
7. Next Steps - Implementation order

Quick Reference Diagrams

Basic API

graph LR
    Client --> W[Worker]
    W --> D1[(D1)]
    W --> KV[(KV Cache)]

Event Pipeline

graph LR
    I[Ingest] --> Q[Queue] --> P[Processor]
    P --> D1[(Storage)]
    P -.->|failed| DLQ[Dead Letter]

Fullstack App

graph LR
    Client -->|/*| Assets
    Client -->|/api/*| API[Worker]
    API --> D1[(D1)]

Related Skills

• implement: Scaffold code with Hono, Drizzle patterns
• loop-breaker: Recursion guards for Worker-to-Worker calls
• guardian: Security and budget auditing
• patterns: Detailed architecture patterns (service-bindings, circuit-breaker, d1-batching)

Reference Files

• references/edge-constraints.md - Node.js API and library compatibility
• references/workload-router.md - Isolates vs Containers vs Python decision trees
• references/workers-assets.md - Pages migration and unified Worker patterns
• references/architecture-templates.md - Pre-built architecture configs
• references/billing-safety.md - Loop protection and anti-patterns