Mina Hooks

The Problem

Diagrams represent an important source of knowledge for companies, describing how their systems work and are integrated.

These pieces of information can be shared as shapes and arrows (diagrams). However, sometimes we are interested in processing this information to create new sets of knowledge or data, such as metrics, analytics, dashboards, etc.

One advantage of adopting the diagrams-as-code approach is the availability of company architecture knowledge in a machine-readable language (DSL), such as PlantUML.

However, to process PlantUML code, you need the following components:

• PlantUML Grammar: First, you need a grammar that describes the PlantUML language to parse it.
• PlantUML Parser: Once you have the grammar, you need a parser that uses the grammar to translate the text into structured data.
• C4 Data Models: The structured data returned from the parser are not easy to read and are often related to the framework used to create the parser. So, you need to translate those data into a data model that reflects the C4 structure.
• Triggers: With the grammar, parser, and readable data models, you are ready to transform PlantUML diagrams into clear, structured data. However, you're still missing the last important piece of the puzzle: a way to trigger this process every time an event occurs, such as the modification of a diagram.

The Solution

Don't worry! Mina has implemented all those components for you!

Thanks to Mina Hooks, you can execute your custom code (e.g., for storing data in a database, creating metrics, analytics, dashboards, etc.) every time an event occurs in Mina (e.g., when a user creates, deletes, or modifies a diagram). The hooks receive in input a structured C4 representation of the diagram(s) affected by the event.

Usage (Node.js)

When you create a new project, Mina generates a hooks.js file in the root of the created project.

This file contains a JavaScript function for each event triggered by Mina. Each function takes as input the structured C4 representation of the diagram(s) (opens in a new tab) affected by the event.

You can add your custom logic in the body of the functions, but make sure to not alter the names of the functions or delete them.

Currently the following hooks are supported. However additional hooks may be added in the future:

• Diagram created
• Diagram deleted
• Diagram modified

hooks.js Example

/**
  * @typedef {Object} Diagram - See {@link https://github.com/keadex/keadex/blob/main/libs/c4-model-ui-kit/src/models/autogenerated/Diagram.ts Diagram}.
  */
 
 /**
  * This hook is triggered when you create a diagram in {@link https://keadex.dev/en/projects/keadex-mina Mina}.
  *
  * @param {Diagram} diagram The created diagram
  */
 async function onDiagramCreated(diagram) {
   // your custom code
 }
 
 /**
  * This hook is triggered when you delete a diagram in {@link https://keadex.dev/en/projects/keadex-mina Mina}.
  *
  * @param {Diagram} diagram The deleted diagram
  */
 async function onDiagramDeleted(diagram) {
   // your custom code
 }
 
 /**
  * This hook is triggered when you save a diagram in {@link https://keadex.dev/en/projects/keadex-mina Mina}.
  *
  * @param {Diagram} diagram The saved diagram
  */
 async function onDiagramSaved(diagram) {
   // your custom code
 }
 
 module.exports = {
   onDiagramCreated,
   onDiagramDeleted,
   onDiagramSaved,
 };