ADR-001: Single Durable Object Class

Status: Accepted
Date: 2026-02-01
Deciders: Abdisamed Mohamed
Related ADRs: ADR-005 (Durable Objects Usage), ADR-002 (Edge-First Architecture)

Context

CepatEdge needs to handle multiple types of data persistence at the edge:

• User sessions (authentication state)
• Data caching (frequent queries)
• Usage metrics (API calls, performance tracking)

Traditional approaches would use separate Durable Object classes for each concern, but this increases complexity and potential cost.

Decision

Implement a single Durable Object class that handles all data types through different namespaces/instances.

Implementation

export class CepatEdgeCache {
  // Single DO class handling multiple data types
  async fetch(request: Request) {
    const pathParts = url.pathname.split('/').filter(Boolean);

    if (pathParts[0] === 'sessions') {
      // Handle session operations
    } else if (pathParts[0] === 'cache') {
      // Handle cache operations
    } else if (pathParts[0] === 'usage') {
      // Handle usage tracking
    }
  }
}

// Usage in wrangler.jsonc
{
  "durable_objects": {
    "bindings": [{
      "name": "CEPATEDGE_CACHE",
      "class_name": "CepatEdgeCache"
    }]
  }
}

// Service usage
const sessions = env.CEPATEDGE_CACHE.get(env.CEPATEDGE_CACHE.idFromName('sessions'));
const cache = env.CEPATEDGE_CACHE.get(env.CEPATEDGE_CACHE.idFromName('cache'));
const usage = env.CEPATEDGE_CACHE.get(env.CEPATEDGE_CACHE.idFromName('usage'));

Consequences

Positive

• Simplified Architecture: One DO class to maintain
• Cost Optimization: Single DO binding instead of multiple
• Consistent API: Same interface patterns across all data types
• Easier Testing: Single mock instead of multiple

Negative

• Single Point of Failure: All data types share the same DO
• Potential Contention: High usage on one data type affects others
• Complexity: Single class handles multiple concerns

Mitigation

• Namespaces: Clear separation through URL routing
• Storage Keys: Prefixed keys prevent conflicts (session:, cache:, usage:)
• Monitoring: Built-in usage tracking to identify bottlenecks
• Future Splitting: Architecture allows easy splitting if needed

Alternatives Considered

Multiple DO Classes

• Pros: Clean separation, independent scaling
• Cons: More complex, higher cost, harder to manage

Redis/Upstash

• Pros: Familiar API, powerful features
• Cons: Additional cost (~$10/month), not edge-native

Cloudflare KV

• Pros: Simple, cost-effective
• Cons: No transactions, eventual consistency

References

• Cloudflare Durable Objects Documentation
• CepatEdge Cost Optimization Strategy