ADR-002: Edge-First Architecture

Status: Accepted
Date: 2026-02-01
Deciders: Abdisamed Mohamed
Related ADRs: ADR-005 (Durable Objects Usage), ADR-003 (Cost Optimization Strategy)

Context

CepatEdge serves university maintenance teams globally. Traditional server-based architectures have several drawbacks:

• Latency: Centralized servers cause high latency for distant users
• Cost: Server management, scaling, and maintenance overhead
• Complexity: Infrastructure management, deployment, monitoring
• Scalability: Limited by server capacity and geographic distribution

Edge computing offers a compelling alternative with Cloudflare's global network of 300+ data centers.

Decision

Adopt an edge-first architecture where all application logic runs at the edge.

Implementation

Technology Stack

• Runtime: Cloudflare Workers (V8 isolates at the edge)
• Framework: Hono (lightweight, fast, edge-optimized)
• Database: Neon Serverless (PostgreSQL-compatible, edge-friendly)
• ORM: Drizzle (lightweight, type-safe, serverless-compatible)
• Caching: Durable Objects (persistent edge storage)
• Frontend: Next.js on Cloudflare Pages

Architecture Pattern

User Request → Cloudflare Edge → Worker Execution → Database Query → Response
                      ↓
               Durable Objects Cache

Key Components

1. API Layer: Hono routes handling REST endpoints
2. Service Layer: Business logic with caching integration
3. Data Layer: Drizzle ORM with Neon Serverless
4. Cache Layer: Durable Objects for sessions and frequent data
5. Auth Layer: JWT with DO-based session validation

Consequences

Positive

• Global Performance: <100ms response times worldwide
• Zero Server Management: No VPS, containers, or orchestration
• Automatic Scaling: Handles traffic spikes automatically
• Cost Efficiency: Pay only for actual usage
• Reliability: Distributed across 300+ data centers

Negative

• Cold Starts: Initial request may have higher latency
• Runtime Limits: 30-second execution limit per request
• Storage Constraints: Durable Objects have size limits
• Debugging Complexity: Distributed execution harder to debug

Mitigation

• Caching Strategy: Minimize cold starts through aggressive caching
• Request Optimization: Keep operations under time limits
• Monitoring: Comprehensive logging and performance tracking
• Development Tools: Local development environment mimics production

Alternatives Considered

Traditional Server Architecture

• Pros: Familiar, full control, no runtime limits
• Cons: High cost, management overhead, scaling complexity

Serverless Functions (AWS Lambda, Vercel)

• Pros: Familiar Node.js environment, generous limits
• Cons: Regional deployment, higher latency for distant users

CDN-Only Architecture

• Pros: Extremely fast for static content
• Cons: No dynamic functionality, limited interactivity

Performance Benchmarks

Target Metrics

• P95 Latency: <200ms globally
• Cache Hit Rate: >90% for frequent requests
• Cold Start Frequency: <1% of requests
• Error Rate: <0.1%

Cost Targets

• Monthly Budget: <$10 for university-scale usage
• Free Tier Utilization: >95% across all services

References

• Cloudflare Workers Documentation
• Hono Framework Documentation
• Neon Serverless Documentation