feat: independent deployment architecture for multi-app CF workers

[koistya]

This PR introduces a deployment configuration that enables independent deployment of three distinct applications (apps/web, apps/app, and apps/edge) while serving them all under the same domain.

🎯 Problem Solved

Previously, all applications were tightly coupled in deployment, meaning any change to the marketing site would require redeploying the entire application stack. This created several pain points:

• Marketing team couldn't update content independently
• Main app deployments were blocked by marketing site changes
• Single point of failure for all applications
• Complex rollback scenarios when issues occurred

🏗️ Architecture Overview

The new architecture separates concerns while maintaining unified domain experience:

example.com/                   → apps/web (Marketing Site - Astro)
example.com/_app/*             → apps/app (Main Application static assets)
example.com/login              → apps/app (Authentication flows)
example.com/account*           → apps/app (User management)
example.com/api/*              → apps/edge (API & WebSocket handler)

Route Priority & Fallbacks

1. apps/app handles specific authenticated routes (/login, /account*, /billing*, /team*, /_app/*)
2. apps/web serves as catch-all for marketing content (/*)
3. apps/edge handles API routes and acts as the orchestration layer

📦 Key Changes by Priority

🟢 High Priority - Core Deployment Configuration

Wrangler Configuration for Independent Deployments

• apps/web/wrangler.jsonc: Marketing site deployment config

  • Catch-all routes for marketing content (example.com/*)
  • Environment-specific deployments (production/staging/preview)
  • Static asset serving configuration

• apps/app/wrangler.jsonc: Main application deployment config

  • Targeted routes for authenticated functionality
  • Specific patterns: /_app/*, /login, /account*, /billing*, /team*
  • Independent versioning and rollback capability

• apps/edge/wrangler.jsonc: Edge worker for API and orchestration

  • API route handling (/api/*)
  • WebSocket connections
  • Database connection pooling via Hyperdrive

Build Output Configuration

• apps/app/vite.config.ts: Optimized asset naming for cache-busting
  • Predictable asset paths: _app/assets/[name]-[hash][extname]
  • Proper chunk splitting for performance
  • Prevents conflicts between apps' static assets

🟡 Medium Priority - Infrastructure & DevOps

Terraform Infrastructure Improvements

• DNS Management: Comprehensive DNS configuration for all environments

  • Production: apex domain + www subdomain
  • Staging: staging.example.com subdomain
  • Preview: 20 named deployment slots ("paris", "london", "tokyo", etc.)

• Enhanced Hyperdrive Configuration:

  • Connection limits (60 connections per pool)
  • Proper caching strategies for read/write workloads
  • Environment-specific database connection pooling

• Required Cloudflare Permissions Update:

  • Added Zone:DNS:Edit permission for automated DNS management
  • Infrastructure can now fully manage DNS records via Terraform

Preview Deployment System

• 20 Named Preview Slots: Each PR gets assigned a memorable codename
• Automated DNS Creation: paris.example.com, london.example.com, etc.

🔵 Low Priority - Security & Performance

Security Headers (apps/web/_headers)

• Comprehensive security header configuration:
  • HSTS with preload directive
  • Content Security Policy preventing XSS
  • X-Frame-Options preventing clickjacking
  • Proper MIME type enforcement

Cache Optimization

• HTML: No caching (max-age=0, must-revalidate)
• Static assets: Long-term caching (max-age=31536000, immutable)
• Images: Reasonable caching (max-age=86400)

Package Cleanup

• Removed duplicate wrangler dependencies from individual apps
• Centralized deployment commands
• Cleaner separation of concerns

🚀 Deployment Flow

Independent Deployment Commands

# Deploy marketing site only
bun wrangler deploy --config apps/web/wrangler.jsonc --env=production

# Deploy main application only  
bun wrangler deploy --config apps/app/wrangler.jsonc --env=production

# Deploy edge worker (API/orchestration)
bun wrangler deploy --config apps/edge/wrangler.jsonc --env=production

Multi-Environment Support

Each app supports three deployment targets:

• Production: Live customer-facing deployment
• Staging: Pre-production testing environment
• Preview: Per-PR deployment with unique subdomain

✅ Benefits for Teams

Marketing Team

• Deploy content updates instantly without engineering bottlenecks
• A/B test landing pages independently
• Roll back marketing changes without affecting the application

Engineering Team

• Deploy application features without waiting for marketing approvals
• Faster rollbacks for critical bugs
• Independent scaling and performance optimization per application

DevOps/Platform Team

• Granular monitoring and alerting per application
• Independent rate limiting and security policies
• Easier debugging with separated concerns

🧪 Testing Strategy

1. Route Validation: Verify all routes resolve to correct applications
2. Cross-App Navigation: Ensure seamless user experience between marketing and app
3. Preview Deployments: Test PR changes in isolation before merge
4. Rollback Testing: Validate independent rollback capabilities

📚 Documentation Updates

• docs/deployment.md: Updated with new deployment commands and architecture
• infra/README.md: Added required Cloudflare permissions
• CLAUDE.md: Updated essential commands for independent deployments

🔄 Migration Path

This change is designed to be backward compatible. Existing single-command deployments continue to work while enabling new independent deployment capabilities.

🤝 For New Contributors

This architecture makes it much easier for new team members to:

• Understand application boundaries and responsibilities
• Deploy changes to specific parts of the system
• Test changes in isolation before affecting the whole system
• Debug issues within a specific application context

The separation of concerns reduces cognitive load and makes the codebase more approachable for developers of all experience levels.