How mhlabs/cfn-diagram works
File structure
• Top-level:
• index.js & index.spec.js – CLI entry point and its unit test.
• graph/ – modules supporting graph generation:
– Vis.js: builds nodes/edges for the vis.js UI
• shared/ – core logic helpers: templateParser.js (walks CFN template, extracts resources and relations), templateCache.js (caches parsed templates).
• tests/ – unit tests for JsonUtil and one sample template.
• .github/ – CI workflows (Node.js build/test, npm publish).
• BUILD.md, README.md, package.json – build instructions, project description, dependencies.
README for additional insights
• Confirms command names, flags, default behaviors (e.g. –skip-synth for CDK, –ci-mode disables prompts).
• Mentions external integration: AWS CDK synth step (invoking CDK CLI), headless Chromium for CI screenshots in companion package.
a. Main components
1. CLI Layer
• index.js uses a command-pattern (e.g. commander.js) to dispatch subcommands.
• Each commands/<format>/index.js implements one “driver” that orchestrates parsing + generation.
2. Core Processing Layer
• shared/templateParser.js: reads & normalizes a CFN/SAM/CDK template, identifies resources, dependencies, nested stacks.
• shared/templateCache.js: caching mechanism if multiple commands reference the same template.
3. Graph Generators
• graph/Vis.js & graph/ui/: builds a JSON graph model (nodes + edges) and injects it into an HTML template with vis.js for interactive output.
• commands/asciiart: calls same parser, then renders a text-based layout via mxgraph-to-asciiart helper.
5. Utilities & Config
• resources/JsonUtil.js: file loading (YAML/JSON), error handling.
• resources/FilterConfig.js & IconMap.js: data to filter or decorate resource nodes.
6. External Integrations
• CDK CLI (child_process spawn for synth)
• AWS CloudFormation API (browse command uses AWS SDK to retrieve deployed stacks)
b. Relationships & interactions
• User invokes “cfn-dia <command>” → index.js → appropriate commands/<cmd>/index.js.
• That module:
1. Loads template with JsonUtil → passes through templateParser → yields resource graph.
2. Optionally invokes CDK synth or AWS SDK browse.
4. Writes output to file system (or stdout).
c. Architectural patterns / design principles
• Command Pattern: isolates each output format’s logic.
• Separation of concerns: parsing, caching, graph model, and rendering are decoupled.
• Plugin-like extensibility: new output format = new commands/<new>/module + generator.
• Data flow is linear: Input → Parse → Model → Render → Output.
d. Key technologies / frameworks
• Node.js, commander.js (CLI), YAML parser, AWS SDK, child_process (CDK), vis.js, mxGraph XML, JSON graph models.