Agent Skills: Cloudflare Architecture Patterns

Cloudflare Architecture Patterns

Proven patterns for solving common Cloudflare architecture challenges. Each pattern includes symptoms (when to apply), detection methods, implementation steps, and trade-offs.

Pattern Catalog

| Pattern | Problem | Solution | Effort | |---------|---------|----------|--------| | service-bindings | Monolithic Worker hitting subrequest limits | Decompose with RPC | Medium | | d1-batching | High D1 write costs from per-row inserts | Batch writes | Low | | circuit-breaker | External API failures cascading | Fail-fast with fallback | Medium |

When to Apply Patterns

Service Bindings Pattern

Trigger Conditions:

• Subrequest count approaching 1,000/request limit
• Single Worker handling unrelated domains (auth, data, notifications)
• HTTP fetch() between internal Workers
• Worker file > 1MB after bundling
• Multiple teams need to deploy independently

Detection (static):

// Anti-pattern: HTTP fetch to internal service
const response = await fetch(`${AUTH_SERVICE_URL}/validate`, {
  headers: { Authorization: token }
});

Detection (live):

• Check observability for high subrequest counts
• Look for latency patterns indicating network hops

D1 Batching Pattern

Trigger Conditions:

• D1 writes represent > 80% of costs
• Per-row INSERT in loops detected in code
• Cron jobs with unbatched writes
• Webhook handlers inserting one record at a time

Detection (static):

// Anti-pattern: Per-row inserts in loop
for (const item of items) {
  await db.run('INSERT INTO items (name) VALUES (?)', [item.name]);
}

Detection (live):

• D1 write count >> expected record count
• High write costs relative to data volume

Circuit Breaker Pattern

Trigger Conditions:

• External API calls without timeout
• No fallback for third-party failures
• Error rate spikes correlating with upstream issues
• User-facing errors caused by backend service outages

Detection (static):

// Anti-pattern: Unbounded external fetch
const data = await fetch('https://external-api.com/data');
// No timeout, no fallback, no retry logic

Detection (live):

• Error rate spikes in observability
• Latency P99 >> P50 (indicating timeouts)
• Correlation between external service status and Worker errors

Pattern Details

Detailed implementation guides are in separate files:

• @service-bindings.md - Decompose monolithic Workers into service-bound microservices
• @d1-batching.md - Optimize D1 write costs with batch operations
• @circuit-breaker.md - Add resilience for external API dependencies

Pattern Selection Guide

Is your Worker > 500 lines or hitting subrequest limits?
├─ Yes → Consider SERVICE-BINDINGS pattern
└─ No
   │
   Is D1 your primary cost driver (>50%)?
   ├─ Yes → Apply D1-BATCHING pattern
   └─ No
      │
      Do you call external APIs?
      ├─ Yes → Apply CIRCUIT-BREAKER pattern
      └─ No → Review other optimization opportunities

Combining Patterns

Patterns can be combined. Common combinations:

1. Service Bindings + D1 Batching: Decompose monolith AND optimize data layer
2. Circuit Breaker + Service Bindings: Each microservice has its own resilience
3. All Three: Large applications benefit from all patterns

Implementation Order (recommended):

1. Circuit Breaker first (lowest risk, immediate resilience benefit)
2. D1 Batching second (cost savings without architecture change)
3. Service Bindings last (largest change, needs careful planning)

Pattern Anti-Patterns

Things to avoid when implementing patterns:

| Pattern | Anti-Pattern | Why It's Bad | |---------|--------------|--------------| | Service Bindings | Too many small Workers | Complexity overhead exceeds benefit | | Service Bindings | Circular dependencies | Deadlock risk, hard to reason about | | D1 Batching | Batches too large | Memory pressure, timeout risk | | D1 Batching | No error handling per batch | One bad record fails entire batch | | Circuit Breaker | Circuit never closes | Permanent degraded mode | | Circuit Breaker | No fallback defined | Fail-fast with no alternative |

Future Patterns (Roadmap)

Patterns to be added:

• read-replication: Durable Objects for regional caching
• event-sourcing: Queues + D1 for audit trails
• rate-limiting: KV-based distributed rate limiting
• edge-caching: Cache API patterns for dynamic content