RFC: Edge/Hybrid Terraform Restructure (Cloudflare + GCP)

[koistya]

Status: Implemented in #2137

Problem

The previous infra/environments/{env}/ structure had issues:

• Environment duplication — each env repeated nearly identical config
• No separation between "what" and "where" — provider config mixed with resources
• Hard to extend — adding GCP support required restructuring

Solution

Two distinct stacks with isolated Terraform roots:

Stack	Components	Use case
edge (default)	Cloudflare Workers, R2, Neon via Hyperdrive	Most SaaS apps
hybrid (opt-in)	Cloud Run, Cloud SQL, GCS	Teams needing Vertex AI or other GCP services

infra/
  modules/{provider}/   # Atomic resources, no credentials
  stacks/{stack}/       # Composable architectures  
  envs/{env}/{stack}/   # Terraform roots (one per env+stack pair)

Key decisions

1. Explicit roots over dispatcher — Each (env, stack) pair gets its own root with isolated state. Avoids the "variable stack" anti-pattern that destroys one stack when switching to another.

2. Providers in env roots only — Modules declare required_providers for source resolution; credentials stay centralized in env roots.

3. Local state by default — Zero-friction onboarding. Remote backend templates available in templates/.

4. Modules must not contain provider blocks — Enforced by CI lint check.

When to use hybrid

Most apps only need the edge stack. Consider hybrid if you specifically need:

• Cloud Run for container workloads
• Vertex AI or other GCP services
• Cloud SQL instead of Neon

If you're not sure, use edge.

[koistya]

• Option A: Ship only edge env roots by default. The hybrid stack modules are there, but teams that need GCP would copy the env root from infra/templates/.
• Option B: Include env roots for both stacks out of the box.

Which do you prefer?