## Context

LWS was built around CDK's `cdk.out` cloud assembly. CDK mode works by parsing CloudFormation templates to discover resources, then pre-creating them locally before the developer's application runs. Terraform works differently — the developer runs `terraform apply` and Terraform itself creates resources via AWS API calls. This means LWS doesn't need to discover or pre-create anything; it just needs to be running and accept whatever Terraform sends.

The management operations added in v0.3.0 (CreateTable, CreateQueue, CreateBucket, etc.) are exactly the APIs that Terraform's AWS provider calls under the hood. The missing piece is telling Terraform to talk to LWS instead of real AWS.

## Goals / Non-Goals

- Goals:
  - `lws dev` works in directories containing `.tf` files
  - `terraform apply` successfully creates infrastructure resources against local LWS endpoints
  - Zero manual configuration — override file is generated and cleaned up automatically
  - Works with both Terraform and OpenTofu
  - Common `terraform apply` workflows complete without errors from missing API stubs

- Non-Goals:
  - Lambda function execution from Terraform-defined functions (requires parsing handler paths from HCL — future work)
  - Parsing `.tf` files or Terraform state to display resources in `lws status` (resources are discoverable via the providers themselves)
  - Supporting Terraform Cloud or remote backends
  - Supporting Terraform providers other than the AWS provider
  - Full API parity with AWS (only stub the operations Terraform commonly calls)

## Decisions

### Decision: Use Terraform override files for endpoint redirection

Terraform merges any file named `*_override.tf` into the configuration automatically. LWS will write `_lws_override.tf` containing an `aws` provider block with custom `endpoints` pointing to local ports.

**Alternatives considered:**
- Require users to manually configure provider endpoints → too much friction, error-prone
- Use environment variables (`TF_VAR_*`) → doesn't work for provider endpoint configuration
- Wrap `terraform` command → too invasive, breaks IDE integrations and CI workflows

### Decision: Auto-detect project type by file presence

LWS will detect the project type by looking for marker files:
- `.tf` files present, no `cdk.out` → Terraform mode
- `cdk.out` present → CDK mode
- Both present → require explicit `--mode` flag
- Neither present → error with guidance

**Alternatives considered:**
- Always require `--mode` flag → unnecessary friction for the common case
- Config file setting → good for advanced use but shouldn't be the only way

### Decision: Stub missing API operations as no-ops

Terraform's AWS provider calls operations beyond basic CRUD (e.g., `TagResource`, `ListTagsForResource`, `UpdateTable`, `DescribeTimeToLive`, `DescribeContinuousBackups`). Rather than implementing full tagging or TTL support, we return empty success responses. This is sufficient for `terraform apply` to succeed.

**Alternatives considered:**
- Implement full API parity → massive scope, most features unused locally
- Return errors for unknown operations → breaks `terraform apply`
- Ignore silently → hard to debug when something genuinely fails

### Decision: No HCL parsing in v1

We will not parse `.tf` files to discover resources. Terraform creates resources itself via `terraform apply`. LWS just needs to accept the API calls. Resource discovery for `lws status` can come from querying the providers (ListTables, ListQueues, etc.) rather than parsing HCL.

**Alternatives considered:**
- Parse HCL with a Python library → adds dependency, fragile, unnecessary since Terraform does the work
- Run `terraform plan -json` → requires Terraform installed and initialized, heavy

## Risks / Trade-offs

- **Risk:** Terraform's AWS provider calls operations we haven't stubbed → `terraform apply` fails
  - Mitigation: Add a catch-all handler that returns empty success for unknown operations in each provider's routes, with a warning log. This is better than failing. Iteratively add proper stubs as we discover what Terraform needs.
- **Risk:** Override file left behind if LWS crashes
  - Mitigation: Check for and clean up stale `_lws_override.tf` on startup. Add comment header to the file explaining it's auto-generated.
- **Risk:** User has existing `_lws_override.tf` file
  - Mitigation: Check before writing, refuse to overwrite if file exists and wasn't generated by LWS (check for marker comment).

## Open Questions

- Should `lws dev` automatically run `terraform init` if `.terraform` directory is missing?
- Should LWS watch `.tf` files for changes and notify the user to re-run `terraform apply`?
- What S3 operations does Terraform's AWS provider use for state backend? (This is out of scope if using local backend, but worth noting.)
