# jsteiml/eventcatalog architecture

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

- Interactive diagram: https://gitdiagram.com/jsteiml/eventcatalog
- Repository: https://github.com/jsteiml/eventcatalog

## Overview

##### Main components
- CLI/Scaffolding Tool – Represented by the “packages/create-eventcatalog” module which provides a command (for example, via npx) to generate new catalogs. This tool uses helper modules to validate the environment, create directories, and generate templated markdown files.
- Core Catalog Engine – This includes the core modules (found in “packages/eventcatalog”, “packages/eventcatalog-types”, and “packages/eventcatalog-utils”) that together parse the markdown files (for events, domains, and services), handle versioning, and build an internal catalog representation.
- Plugin Architecture – Represent the subsystem that supports third-party plugins (e.g. “packages/eventcatalog-plugin-generator-asyncapi” and “packages/eventcatalog-plugin-generator-amazon-eventbridge”). These plugins extend or generate documentation files from different event or schema standards.
- Frontend Web UI – The website is built using Next.js (see “packages/eventcatalog/pages”, “components”, “styles”, etc.) and is responsible for rendering pages (like domain overview, events detail, services, and visualisations). It integrates MDX for rich documentation consumption.
- File-based Markdown Repository – Because the system is “markdown driven,” include a component to represent the repository of markdown files, organized into “domains”, “events”, “services”, with versioning and changelogs (e.g., under the “examples” folder and similar directories in the create eventcatalog templates).
- Website Documentation – Also include the “website” directory that holds the external public docs and blog for EventCatalog to help users on installation, usage, and plugin information.

##### Relationships and interactions
- Data Flow – Show that the user writes or updates markdown files (documenting events, services, etc.) in their repository. The CLI tool uses these files for scaffolding or updating the catalog.
- Catalog Engine – Next, illustrate how the core library reads these markdown files (using file-reader utilities) and constructs an internal model of the event architecture. This model then is consumed by the web UI.
- Development and Testing Tools – Also represent development flows with contributors using linting (Workflows, ESLint, Prettier configs) and testing scripts (jest) integrated into the CI/CD pipelines.

##### Architectural patterns and design principles
- Modular Monorepo – The repository is structured as a monorepo managed by Lerna, separating concerns among CLI, plugins, core types/utilities, and the website.
- Plugin-based Extensibility – The system is designed to be technology agnostic, letting third-party plugins integrate with various schema standards.
- File/Configuration Driven – The entire catalog is built around markdown and configuration files (like eventcatalog.config.js) thus demonstrating a static-content, build-time generation approach.
- Next.js Frontend – The website follows Next.js conventions (pages, API routes, public static assets) and leverages MDX for enhanced documentation.

##### Final Advice
- Be as detailed as possible by including each major module (even listing examples like “packages/create-eventcatalog”, “packages/eventcatalog-plugin-generator-asyncapi”, etc.) to capture the modular nature of the project.
- Dependencies among modules and include labels for configuration files that drive the behavior of each subsystem.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User: Writes Markdown Files"]:::user
    R["Markdown Repository"]:::repo

    subgraph "Scaffolding Layer"
        C["CLI/Scaffolding Tool"]:::cli
    end

    subgraph "Core Catalog Engine"
        E1["Catalog Engine (packages/eventcatalog)"]:::engine
        E2["Catalog Types (packages/eventcatalog-types)"]:::engine
        E3["Catalog Utils (packages/eventcatalog-utils)"]:::engine
    end

    subgraph "Plugin Architecture"
        P1["AsyncAPI Plugin (packages/eventcatalog-plugin-generator-asyncapi)"]:::plugin
        P2["Amazon EventBridge Plugin (packages/eventcatalog-plugin-generator-amazon-eventbridge)"]:::plugin
    end

    subgraph "Frontend Web UI (Next.js)"
        F1["Next.js Pages (packages/eventcatalog/pages)"]:::ui
        F2["UI Components (packages/eventcatalog/components)"]:::ui
    end

    subgraph "Website Documentation"
        D1["Docs (website/docs)"]:::doc
        D2["Blog (website/blog)"]:::doc
    end

    subgraph "Utility Modules & Build/Dev Tools"
        B1["Scripts (scripts)"]:::build
        B2["Jest Tests (jest)"]:::build
        B3["Config: .eslintrc.js"]:::build
        B4["Config: lerna.json"]:::build
    end

    %% Data Flow
    U -->|"writesMarkdown"| R
    R -->|"providesFiles"| C
    C -->|"generatesCatalog"| E1
    C --> E2
    C --> E3
    E1 -->|"buildsModel"| E2
    E2 -->|"parsesAndVersion"| E3
    E1 -->|"sendsModel"| P1
    E1 --> P2
    P1 -->|"transformsModel"| E1
    P2 -->|"transformsModel"| E1
    E1 -->|"outputsCatalog"| F1
    E1 --> F2
    F1 -->|"rendersPages"| F2
    F2 -->|"displaysVisuals"| D1
    F2 --> D2

    %% Integration with Build/Dev Tools
    B1 -->|"runsScripts"| C
    B2 -->|"testsCore"| E1
    B3 -->|"configuresRepo"| R
    B4 -->|"managesMonorepo"| R

    %% Click Events
    click C "https://github.com/jsteiml/eventcatalog/tree/master/packages/create-eventcatalog"
    click E1 "https://github.com/jsteiml/eventcatalog/tree/master/packages/eventcatalog"
    click E2 "https://github.com/jsteiml/eventcatalog/tree/master/packages/eventcatalog-types"
    click E3 "https://github.com/jsteiml/eventcatalog/tree/master/packages/eventcatalog-utils"
    click P1 "https://github.com/jsteiml/eventcatalog/tree/master/packages/eventcatalog-plugin-generator-asyncapi"
    click P2 "https://github.com/jsteiml/eventcatalog/tree/master/packages/eventcatalog-plugin-generator-amazon-eventbridge"
    click F1 "https://github.com/jsteiml/eventcatalog/tree/master/packages/eventcatalog/pages"
    click F2 "https://github.com/jsteiml/eventcatalog/tree/master/packages/eventcatalog/components"
    click R "https://github.com/jsteiml/eventcatalog/tree/master/examples"
    click B1 "https://github.com/jsteiml/eventcatalog/tree/master/scripts"
    click B2 "https://github.com/jsteiml/eventcatalog/tree/master/jest"
    click B3 "https://github.com/jsteiml/eventcatalog/blob/master/.eslintrc.js"
    click B4 "https://github.com/jsteiml/eventcatalog/blob/master/lerna.json"

    %% Styles
    classDef user fill:#ffffff,stroke:#000000,stroke-width:2px;
    classDef repo fill:#e8daef,stroke:#9b59b6,stroke-width:2px;
    classDef cli fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef engine fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef plugin fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef ui fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef doc fill:#d6eaf8,stroke:#2980b9,stroke-width:2px;
    classDef build fill:#f7dc6f,stroke:#f1c40f,stroke-width:2px;
```
