refactor: modernize codebase architecture with established design patterns #708
Description
Overview
As the plugin has grown to support more AWS service integrations, several modules have become difficult to navigate and maintain. This is a roadmap issue tracking a series of focused refactors — each self-contained and independently mergeable — that apply established design patterns to improve the long-term maintainability of the codebase.
No public API or configuration changes are involved in any of these.
Proposed Refactors
1. compileIamRole — Strategy pattern (tracked in #707)
compileIamRole.js (~1000 LOC) and its test file (~4700 LOC) have grown into monoliths as new AWS service integrations were added. The getIamPermissions() dispatcher is a large if/else if chain routing to 30+ permission-generating functions.
Proposal: Introduce a iamRole/strategies/ directory where each AWS service integration (SNS, SQS, DynamoDB, S3, Lambda, Step Functions, Redshift, etc.) is a self-contained strategy module exporting matches(resource) and getPermissions(state). The dispatcher iterates the strategy registry — adding a new service integration becomes a single new file with no changes to existing code.
2. compileNotifications — Strategy pattern
compileNotifications.js (~396 LOC) dispatches on notification target type (SNS, SQS, Kinesis, Lambda, etc.) using string matching. The same pattern problem as compileIamRole — target-specific logic is mixed together, making it hard to add or modify individual targets.
Proposal: Mirror the iamRole approach with a notifications/strategies/ directory — one file per target type, each exporting a consistent interface.
3. Schedule & CloudWatch events — shared validation utility
compileScheduledEvents.js and compileCloudWatchEventEvents.js both contain near-identical logic for:
- Validating
Input/InputPath/InputTransformermutual exclusivity - Generating IAM role CloudFormation templates (differing only in the principal service)
Proposal: Extract a shared event input validator and an IAM role template factory parameterised by principal service (scheduler.amazonaws.com vs events.amazonaws.com). Low effort, high clarity gain.
4. naming.js — Factory pattern
naming.js contains 10+ near-identical get*LogicalId() methods (e.g. getStateMachineLogicalId, getActivityLogicalId, getScheduleLogicalId, getSchedulerScheduleLogicalId) that all follow the same normalization convention.
Proposal: Replace with a generic generate(resourceType, name, suffix?) factory method, reducing repetition and making it trivial to add logical ID generation for new resource types.
5. API Gateway compilation pipeline — Chain of Responsibility
index.js wires the 14 API Gateway compilation steps as a hardcoded .then() chain. While the individual modules are well-sized, the pipeline itself is rigid and difficult to extend.
Proposal: Introduce a CompilationPipeline that accepts an ordered list of compiler steps. Steps become reorderable, conditionally includable, and the chain no longer lives in index.js.
Dependency note
Refactors #1 and #2 should be preceded by merging any open PRs that touch compileIamRole.js / compileNotifications.js, so the restructured code starts from a complete, up-to-date baseline. Current relevant open PRs: #706, #705, #702, #699, #697, #696, #695, #694, #693, #692.
Question for maintainers
Does this roadmap align with the direction you want to take the codebase? We are happy to:
- Work through these one at a time in the priority order listed above
- Discuss scope or approach on any individual item before starting
- Adjust the proposal based on your feedback
We see #1 as the highest priority given the size of compileIamRole, and the others as natural follow-ons once the pattern is established.