ADR-005: Example Naming Convention (MVP/PoC/Production Tiers)

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

Context

The source iam-identity-center module has 16 examples with ad-hoc naming:

ai-agent-permissions/
create-apps-and-assignments/
create-users-and-groups/
create-users-and-groups-with-customer-managed-policies/
entra-pim-integration/
existing-users-and-groups/
existing-users-groups-create-apps/
google-workspace/
inline-policy/
instance-access-control-attributes/
jit-access/
localstack/
test-minimal/

Problems with current naming:

1. No indication of COMPLEXITY (is jit-access production-ready or experimental?)
2. No indication of COST (does entra-pim-integration spin up $200/month of resources?)
3. No indication of AUDIENCE (is test-minimal for testing or for new users?)
4. test-minimal is ambiguous: is it a test fixture or a minimal usage example?
5. No ordering — alphabetical sort doesn't reflect learning progression

The aws-ecs-fargate module has only one example: dashboard-deployment/ — insufficient.

The web module examples are undefined.

Industry reference: The terraform-aws-modules organisation uses a simpler flat structure (examples/complete/, examples/basic/, examples/disabled/) which doesn't scale to modules with multiple IdP integrations, JIT access patterns, and ABAC configurations.

The manager brief specifies three example tiers: MVP, PoC, Production. These map naturally to cost and complexity axes.

Decision

Adopt a three-tier prefix system with kebab-case descriptors:

examples/
├── mvp-<descriptor>/        # Tier 1: Minimum viable, $0-5/month, no HITL required
├── poc-<descriptor>/        # Tier 2: Proof of concept, $5-50/month, HITL approval required
└── production-<descriptor>/ # Tier 3: Production-ready, $50+/month, HITL mandatory

The naming pattern is {tier}-{descriptor} (e.g., mvp-minimal, poc-abac, production-jit-access).

Tier definitions:

Tier	Prefix	Resources Created	Estimated Monthly Cost	HITL Gate	Intended Audience
MVP	mvp-	Plan-only OR minimal apply (groups + permission sets, no users)	$0-5	Not required	New users, CI testing, Registry docs
PoC	poc-	Functional apply with real IdP integration OR 1 ECS service	$5-50	Required (Tier 3)	Evaluators, sandbox testing
Production	production-	Full compliance stack: JIT, ABAC, Zero Trust, multi-account	$50-500+	Mandatory	Enterprise architects

Concrete mapping for iam-identity-center:

Old Name	New Name	Tier	Rationale
test-minimal	mvp-minimal	MVP	Plan-only; used in Tier 1 tests
localstack	(move to tests/)	N/A	Test fixture, not an example
create-users-and-groups	mvp-users-and-groups	MVP	Basic user provisioning
existing-users-and-groups	mvp-existing-idp	MVP	Read-only, plan validation
inline-policy	mvp-inline-policy	MVP	Single permission set pattern
instance-access-control-attributes	poc-abac	PoC	Requires real SSO instance
create-apps-and-assignments	poc-sso-applications	PoC	Requires real AWS account
existing-users-groups-create-apps	poc-hybrid-idp	PoC	Mixed existing + new
create-users-and-groups-with-customer-managed-policies	poc-customer-managed-policies	PoC	Real IAM policies
google-workspace	poc-google-workspace	PoC	Requires Google Workspace setup
entra-pim-integration	production-entra-pim	Production	Requires Entra + AWS Organizations
jit-access	production-jit-access	Production	Lambda + SNS + EventBridge
ai-agent-permissions	production-ai-agent-rbac	Production	Zero Trust + ABAC + JIT

Each example directory MUST contain:

mvp-minimal/
├── main.tf
├── variables.tf
├── outputs.tf
├── versions.tf
├── README.md          # cost estimate, prerequisites, time-to-apply
└── terraform.tfvars.example

README.md header template:

# Example: <Tier> - <Descriptor>

**Tier**: MVP | PoC | Production
**Cost**: $X/month (ap-southeast-2)
**Time to Apply**: X minutes
**Prerequisites**: [list]
**HITL Required**: Yes | No

Consequences

Positive

• Users immediately understand complexity, cost, and audience from directory name
• CI can automatically skip production-* examples unless HITL approval present
• Registry documentation auto-generated example list has meaningful ordering
• Consistent with ADLC 3-tier testing philosophy

Negative

• 13 existing example directories need renaming — breaking change for any consumer who references example directories directly (unlikely but possible)
• Longer directory names increase path verbosity in README source blocks

Blocking Risks

Risk	Probability	Impact	Mitigation
Tier mis-classification (PoC example that actually costs Production-level)	Low	Medium	Each example README has a cost estimate validated by Infracost in CI; PR gate fails if estimated cost deviates >20% from tier threshold

Alternatives Considered

1. Keep existing ad-hoc names: Rejected — no discoverability; test fixtures mixed with examples
2. basic/, complete/, advanced/ (terraform-aws-modules pattern): Rejected — "complete" is ambiguous (complete feature set or complete configuration?); does not convey cost or HITL
3. Numbered prefixes (01-minimal, 02-abac): Rejected — numbers imply sequential dependency which is false; MVP examples are standalone

Related ADRs

• ADR-001: Module naming convention establishes the kebab-case standard that example names inherit
• ADR-004: Three-tier testing strategy maps directly to example tiers (MVP = Tier 1, PoC = Tier 2, Production = Tier 3)

References

• Terraform Registry: Module Documentation: https://developer.hashicorp.com/terraform/registry/modules/publish#documentation
• terraform-aws-modules example conventions: https://github.com/terraform-aws-modules/terraform-aws-vpc/tree/master/examples
• ADLC 3-Tier Testing: sandbox/.specify/memory/constitution.md (Principle IV)

Coordination Evidence

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