# AWS Infrastructure

## Infrastructure as code

- Every AWS resource is managed by infrastructure as code. Do not create Lambdas, roles, buckets, or anything else by hand in the console.
- **Terraform** (run by HCP Terraform) is the default for all new projects.
- Some existing projects use **AWS SAM** or **AWS CDK**. Keep working in the tool the project already uses. Do not start a new project on SAM or CDK without agreement from Sea Haven.
- Terraform creates the infrastructure. The CI/CD pipeline deploys the application code into it. Terraform does not package or deploy application code.

## Lambda defaults

Every Lambda function uses these settings:

| Setting | Value |
|---|---|
| Runtime | Python 3.12, or Node.js 24 (`nodejs24.x`) |
| Architecture | `arm64` |
| Log retention | 60 days, set explicitly in code |
| Name | kebab-case, prefixed with the stack or repo name |

- Always set log retention explicitly. The AWS default keeps logs forever.
- Do not start new functions on older Node runtimes such as `nodejs22.x`.
- Give each function an IAM role with only the permissions it needs. Never use `AdministratorAccess` or broad wildcards.

## S3

- Tag every bucket with `Purpose` and `ManagedBy`.
- Define lifecycle policies in code.
- Use Glacier Deep Archive for archival data.

## Outputs

Every stack exposes the function ARNs and any externally used URLs (such as API endpoints) as outputs.

## Dependency versions

- Pin dependencies to exact versions and commit the lockfile.
- Automated dependency-update PRs keep those pins current. Do not disable them or add blanket ignore rules.
- If one specific release is broken, ignore only that release, with a comment explaining why.

## README

Every repo has a README that accurately describes:

- Architecture
- Services and functions
- Data flow
- Required configuration

Update the README in the same PR that changes the behavior it describes.

## Project layout (Terraform)

```
project-name/
├── terraform/          # Infrastructure (applied by HCP Terraform)
│   ├── bootstrap/      # Placeholder packages so Terraform can create functions
│   ├── lambda.tf
│   ├── s3.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── versions.tf
├── src/                # Application code (deployed by the pipeline)
├── .github/
│   └── workflows/
│       ├── ci.yaml
│       └── deploy-<name>.yaml
└── README.md
```

CI runs `terraform fmt -check -recursive` and `terraform validate` on every PR. Terraform plans for PRs run in HCP Terraform.