ADR-001: Module Naming Convention

Status: Accepted Date: 2026-02-25 Deciders: @cloud-architect, @product-owner, HITL/Manager

Context

The terraform-aws repository must be publishable to the Terraform Registry under https://registry.terraform.io/modules/oceansoft/. HashiCorp's Registry naming convention (https://developer.hashicorp.com/terraform/registry/modules/publish#requirements) mandates the repository name format terraform-<PROVIDER>-<NAME>.

Inside the repository, three module directories need internal naming conventions for:

• modules/ directory naming (the <NAME> portion within the monorepo)
• Example directory naming
• Variable/output naming within HCL code

Two conventions are in active use in the codebase today:

• snake_case: HashiCorp's official style guide (https://developer.hashicorp.com/terraform/language/style#naming) uses snake_case for resource names, variable names, output names, and local values.
• kebab-case: Community convention from terraform-aws-modules (github.com/terraform-aws-modules) uses kebab-case for MODULE DIRECTORY names (e.g. modules/iam-identity-center, modules/aws-ecs-fargate).

This is not a contradiction: the two conventions apply to different scopes.

Decision

Apply convention by scope:

Scope	Convention	Rationale
Repository name	terraform-aws-<name> kebab	Registry REQUIREMENT, non-negotiable
Module directory names	kebab-case	Matches terraform-aws-modules community standard; consistent with existing source modules
HCL identifiers (resources, vars, outputs, locals)	snake_case	HashiCorp style guide REQUIREMENT
Example directory names	kebab-case (with tier prefix)	See ADR-005 for example naming
File names	snake_case with hyphens for multi-word (e.g. cross-account-audit.tf)	Matches existing codebase

Concrete module directory names adopted:

• modules/iam-identity-center/ (existing, keep as-is)
• modules/ecs-platform/ (rename from aws-ecs-fargate — rationale: Registry NAME must be meaningful; "ecs-platform" signals composition beyond raw Fargate service; "aws-" prefix is redundant inside an aws-provider repository)
• modules/web/ (new)

Registry module addresses published as:

• oceansoft/iam-identity-center/aws
• oceansoft/ecs-platform/aws
• oceansoft/web/aws

Consequences

Positive

• Zero naming friction with terraform-aws-modules ecosystem (consumers know what to expect)
• Registry URL is clean and descriptive without "aws-" redundancy
• HCL identifiers remain HashiCorp-compliant (passes tflint --enable-plugin=aws)

Negative

• The existing source module is named aws-ecs-fargate; renaming to ecs-platform requires a CUSTOMIZATIONS.md update to document the rename. Minor friction only.
• Snake_case vs kebab split requires a one-line decision matrix in CONTRIBUTING.md.

Blocking Risks

Risk	Probability	Impact	Mitigation
Future contributors use wrong convention in wrong scope	M	L	tflint + pre-commit hook enforcing snake_case in HCL identifiers

Alternatives Considered

1. All kebab-case everywhere: Rejected — violates HashiCorp style guide for HCL identifiers
2. All snake_case everywhere: Rejected — module directories with snake_case are not idiomatic; terraform-aws-modules (the most-used Terraform module library) uses kebab for directories
3. PascalCase for module names: Rejected — not valid in HCL identifiers; Registry doesn't prohibit it for repos but it's non-idiomatic

Related ADRs

• ADR-002: Registry Structure — Defines the monorepo source vs thin-wrapper publishing pattern that these module names map to
• ADR-005: Example Naming — Extends this convention to example directory tier prefixes

References

• HashiCorp Style Guide: https://developer.hashicorp.com/terraform/language/style
• Registry Publishing Requirements: https://developer.hashicorp.com/terraform/registry/modules/publish#requirements
• terraform-aws-modules naming: https://github.com/terraform-aws-modules

Coordination Evidence

Consolidated from .adlc/projects/terraform-aws/ as part of ADR-001→019 SSOT consolidation (2026-02-27).