Why Diagram‑as‑Code Matters: Designing the Feakin Conceptual System Tool

Diagram-as-Code Overview

Diagram-as-Code treats a diagram as a first‑class artifact expressed in a domain‑specific language (DSL). The DSL can be JSON, XML, or a lightweight textual syntax such as Graphviz’s DOT, enabling version control, automated generation, and transformation into secondary artifacts (concept maps, architecture diagrams, software design schematics).

Domain‑Specific Language (DSL)

A DSL provides a concise textual representation of nodes and edges. The following DOT example defines a simple directed graph:

digraph G {
  a -> b
  b -> c
}

Additional configuration (styles, sub‑graphs, attributes) can be added as needed.

Tool Landscape

Visualization engines (e.g., Graphviz, Mermaid) render DSL files directly in documentation or READMEs.

Code‑generation tools (e.g., PlantUML, Structurizr DSL) produce source code or scaffolding from diagram models.

Interactive editors (e.g., Ledge) allow direct manipulation of the rendered graphic with live DSL updates.

Layout Computation

Automatic layout algorithms compute node positions from the DSL model. Common algorithms include Dagre, Force‑Layout, ELK, CoSE, and Cola. A pluggable layout interface—illustrated by Cytoscape.js—enables integration of additional algorithms without changing the core model.

Bidirectional Binding

Two‑way synchronization keeps the DSL source and the visual representation consistent. When the user edits the graphic, the underlying DSL is regenerated; when the DSL changes, the view is refreshed. Implementations must handle actions such as undo/redo by reloading the data model.

Feakin – Concept‑Centric Diagram Engine

Feakin is an open‑source project (GitHub: https://github.com/feakin/) that aims to provide a hierarchical, concept‑oriented diagram engine distinct from data‑driven libraries (e.g., ECharts, Ant G6). Its primary objectives are:

Support for layered, hierarchical thinking in architecture and knowledge graphs.

Clear separation between the abstract diagram model and the rendering engine.

Abstract Diagram Model

Feakin defines a platform‑agnostic abstract diagram model that can be rendered by a dedicated engine (Feakin Render). The current proof‑of‑concept uses react‑konva for Canvas‑based rendering and exposes basic rendering and layout interfaces.

Demo repository: https://github.com/feakin/diagram-render

Current State and Limitations

PoC supports only fundamental rendering and layout capabilities.

Compatibility with Draw.io is limited because the underlying mxGraph library is no longer maintained.

Future work includes completing a robust abstract model, extending the render engine, and providing extensible programming APIs for plugins.

Technical Details

The repository structure separates the model definition, layout adapters, and rendering components. Layout adapters implement a generic interface that receives a model graph and returns node coordinates, allowing easy substitution of algorithms such as Dagre or ELK. Rendering components consume the coordinates and draw shapes on a Canvas via react‑konva.

Key repository paths: /model – definition of the abstract diagram entities (nodes, edges, groups). /layout – adapters for layout algorithms. /render – Canvas rendering implementation.

Developers can clone the project with git clone https://github.com/feakin/feakin.git and run the demo using standard Node.js tooling (e.g., npm install && npm start).