How zenuml/core works
Main Components
• Parser Module: This section involves the DSL parser, built using Antlr4. Note that the grammar definitions are under the “src/g4” folder, the generated parser files are in “src/generated-parser”, and further enhancements reside in “src/parser”. Include subcomponents like modules for handling different aspects of the DSL (e.g., Creation, Divider, Fragment, Participants, Title, etc.).
• Testing and CI/CD: Notice the extensive test directories (“cypress”, “test/unit”, etc.) and CI/CD configurations using GitHub Actions (in “.github/workflows”). This demonstrates a structured testing framework (integration tests, UI tests, parser tests) and deployment automation (e.g., building and publishing to GitHub Pages).
• Integration Layer: There are directories like “Integration” and “playground” along with documentation (e.g., in “docs/asciidoc/integration-guide.adoc”) to guide embedding ZenUML in external tools and platforms.
• Utility and Support Layers: Additional modules like “src/utils”, “src/positioning”, “src/plugins”, and “src/store” provide support functionalities such as coordinate calculations for positioning message blocks, plugin enhancements, and internal state management.
Relationships and Interactions
• The DSL input (in Markdown-like syntax) is first processed by the Parser Module. This module takes text as input, applies the Antlr-defined grammar (with additional parsing logic in “src/parser”), and produces an intermediate representation.
• The CI/CD pipeline (defined in “.github/workflows”) continuously tests both the parser and renderer modules and deploys the final build.
• Additionally, the integration layer allows embedding ZenUML into other environments; consider how external communication might be achieved (e.g., configuration files in “env”, integration guides, etc.).
Architectural Patterns and Design Principles
• Separation of Concerns: The project clearly separates the parsing logic from the rendering logic. This modularity simplifies maintenance and integration.
• Automated Testing & Continuous Integration: The presence of both unit and integration tests along with GitHub Actions workflows indicates strong practices in ensuring quality and reliability.
• Extensibility: The use of plugins and a well-documented integration guide suggests the system is designed to be extended or embedded in other platforms.
Technologies, Frameworks, and Libraries
• Antlr4 for DSL parsing (located within “antlr” and “src/g4”).
• Vue.js (components in “src/components”) for the rendering layer.
• Testing frameworks: Cypress for end-to-end tests, and various unit test files (often with TypeScript or JavaScript) spread across “test/unit” and “cypress”.
• Build tools and dependency management: Various configuration files (package.json, pnpm-lock.yaml, vite config files) indicate use of modern JavaScript tooling.
• Tailwind CSS: There's a “tailwind.config.js” and source SCSS files for styling.