# zenuml/core architecture

> Architecture diagram of the GitHub repository zenuml/core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zenuml/core
- Repository: https://github.com/zenuml/core

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    DSL["DSL Input (Markdown)"]:::input
    DSL -->|"parses_to"| ParserM

    subgraph "Parser Module"
        Grammar["Grammar Definitions"]:::parserChild
        Antlr["Antlr-Generated Parser Files"]:::parserChild
        Enhancements["Parser Enhancements & Submodules"]:::parserChild
        Grammar -->|"contributes_to"| Intermediate
        Antlr -->|"contributes_to"| Intermediate
        Enhancements -->|"contributes_to"| Intermediate
    end
    ParserM[" "]:::module
    ParserM -->|"generates"| Intermediate

    Intermediate["Intermediate Representation"]:::data
    Intermediate -->|"renders_to"| RendererM

    subgraph "Renderer Module"
        VueComp["Vue.js Components (Diagram Frame, Sequencing, Tutorial, etc.)"]:::rendererChild
    end
    RendererM[" "]:::module
    RendererM --> VueComp

    VueComp -->|"loads_assets_from"| Assets
    VueComp -->|"applies_styles_from"| Themes

    Utilities["Utility & Support Layers"]:::utility
    Utilities -->|"supports"| ParserM
    Utilities -->|"supports"| RendererM

    subgraph "Utility and Support"
        Utils["Utility Functions"]:::utilityChild
        Position["Positioning & Layout Calculations"]:::utilityChild
        Plugins["Plugin Enhancements"]:::utilityChild
        Store["State Management (Store)"]:::utilityChild
    end

    Testing["Tests (Cypress & Unit)"]:::ci
    Testing -->|"tests"| ParserM
    Testing -->|"tests"| RendererM

    CICD["CI/CD Pipeline"]:::ci
    CICD -->|"deploys"| RendererM

    Integration["Integration & Embedding (Examples, Docs)"]:::integration
    Integration -->|"embeds_widget_in"| RendererM

    %% Click Events
    click Grammar "https://github.com/zenuml/core/tree/main/src/g4"
    click Antlr "https://github.com/zenuml/core/tree/main/src/generated-parser"
    click Enhancements "https://github.com/zenuml/core/tree/main/src/parser"
    click VueComp "https://github.com/zenuml/core/tree/main/src/components"
    click Assets "https://github.com/zenuml/core/tree/main/src/assets"
    click Themes "https://github.com/zenuml/core/tree/main/src/themes"
    click Testing "https://github.com/zenuml/core/tree/main/test/unit"
    click CICD "https://github.com/zenuml/core/tree/main/.github/workflows"
    click Integration "https://github.com/zenuml/core/tree/main/Integration"
    click Utils "https://github.com/zenuml/core/tree/main/src/utils"
    click Position "https://github.com/zenuml/core/tree/main/src/positioning"
    click Plugins "https://github.com/zenuml/core/tree/main/src/plugins"
    click Store "https://github.com/zenuml/core/tree/main/src/store"

    %% Styles
    classDef module fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef parserChild fill:#E3F2FD,stroke:#0D47A1,stroke-width:1px;
    classDef rendererChild fill:#E8F5E9,stroke:#1B5E20,stroke-width:1px;
    classDef asset fill:#F3E5F5,stroke:#4A148C,stroke-width:1px;
    classDef ci fill:#FFCCBC,stroke:#BF360C,stroke-width:1px;
    classDef integration fill:#FFE082,stroke:#FF6F00,stroke-width:1px;
    classDef utility fill:#E0E0E0,stroke:#424242,stroke-width:1px;
    classDef utilityChild fill:#F5F5F5,stroke:#616161,stroke-width:1px;
    classDef input fill:#FFF9C4,stroke:#F9A825,stroke-width:1px;
    classDef data fill:#DCEDC8,stroke:#558B2F,stroke-width:1px;
```
