How jsteiml/eventcatalog works
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.