PlantKit

PlantKit is a TypeScript library for generating PlantUML ArchiMate diagrams programmatically. It supports the ArchiMate 3.2 element and relationship vocabulary rendered through Archimate-PlantUML macros.

Key Features

• 🏗️ ArchiMate 3.2 Vocabulary: 65+ element types and 77+ relationship variants across all layers
• 🌳 Dual Modeling Architecture: Hierarchical element trees for visual organization + semantic relationship graphs
• 🎨 Advanced Diagram Generation: Automatic sprite management, legends, scaling, and layout control
• 🔧 Enterprise-Ready: Property management, validation, type safety, and production-quality PlantUML output
• 📝 TypeScript Native: Full type safety with comprehensive type definitions
• 🚀 Developer Friendly: Intuitive API with utility functions and debugging support

Architecture Overview

PlantKit uses a dual modeling approach that separates visual presentation from semantic relationships:

Core Components

• Element - Hierarchical tree structures for visual grouping and nesting
• ElementGraph - Semantic relationships between elements (composition, flow, etc.)
• Diagram - PlantUML generation with sprites, legends, and formatting
• PlantKit - Conversion utilities and output generation
• ArchimateElement - Type-safe ArchiMate element creation
• ArchimateRelation - Type-safe ArchiMate relationship creation

ArchiMate Support

Element Types (65+ supported)

PlantKit supports all ArchiMate 3.x element types across all layers:

• Strategy Layer: Resource, Capability, Course of Action, Value Stream
• Business Layer: Actor, Role, Collaboration, Interface, Process, Function, Interaction, Event, Service, Object, Contract, Representation, Product, Location
• Application Layer: Component, Collaboration, Interface, Function, Interaction, Process, Event, Service, Data Object
• Technology Layer: Node, Device, System Software, Collaboration, Interface, Path, Communication Network, Function, Process, Interaction, Event, Service, Artifact
• Physical Layer: Equipment, Facility, Distribution Network, Material
• Motivation Layer: Stakeholder, Driver, Assessment, Goal, Outcome, Principle, Requirement, Constraint, Meaning, Value
• Implementation Layer: Work Package, Deliverable, Event, Plateau, Gap
• Other Elements: Location, Junction (Or/And), Grouping, Group

Relationship Types (77+ supported)

Complete support for all ArchiMate relationships with directional variants:

• Structural: Composition, Aggregation, Assignment, Specialization
• Dependency: Serving, Association, Flow, Realization, Triggering
• Dynamic: Access (read/write/read-write variants), Influence
• Directional Variants: Up, Down, Left, Right for all relationship types

Installation

npm install plantkit

Quick Start

Simple API (Recommended)

import { PlantKit } from 'plantkit';

// Create diagram with fluent API
const output = PlantKit.create('business-model', 'Business Model')
  .addElement('customer', 'Business_Actor', 'Customer')
  .addElement('orderProcess', 'Business_Process', 'Order Processing')
  .addRelation('customer', 'orderProcess', 'Rel_Triggering', 'initiates')
  .generate();

console.log(output);

Advanced API (Full Control)

For complex scenarios requiring hierarchies or advanced features:

import { Element, ElementGraph, Diagram, PlantKit } from 'plantkit';

// Create elements with properties
const customer = new Element('Customer', { 
  type: 'Business_Actor', 
  label: 'Customer' 
});

const orderProcess = new Element('Order Process', { 
  type: 'Business_Process', 
  label: 'Order Processing' 
});

// Create element graph for relationships
const graph = new ElementGraph();
graph.addNode(customer);
graph.addNode(orderProcess);
graph.addRelation(customer, orderProcess, 'Rel_Triggering', { label: 'initiates' });

// Generate PlantUML diagram
const diagram = new Diagram('business-model', 'Business Model');
const plantkit = new PlantKit();

// Add elements to diagram
diagram.addToBody(plantkit.toArchimate(customer));
diagram.addToBody(plantkit.toArchimate(orderProcess));
diagram.addToBody(plantkit.toArchimateRelations(graph));

// Output PlantUML
console.log(diagram.output());

Core Concepts

Element Trees vs. Relationship Graphs

PlantKit uses a dual modeling approach:

1. Element Trees (Element class): Hierarchical structures for visual organization and nesting in diagrams
2. Relationship Graphs (ElementGraph class): Semantic relationships between elements (composition, flow, etc.)

This separation allows you to:

• Organize elements visually (e.g., group related components)
• Define semantic relationships independently (e.g., data flows, dependencies)
• Generate clean, readable diagrams with proper ArchiMate semantics

Properties and Metadata

Elements and relationships support arbitrary properties:

const element = new Element('Database', {
  type: 'Technology_Node',
  label: 'Customer Database',
  technology: 'PostgreSQL',
  version: '14.0'
});

graph.addRelation(app, database, 'Rel_Access_rw', {
  label: 'reads/writes',
  protocol: 'JDBC'
});

API Reference

PlantKit Facade (Simple API)

The PlantKit class provides a fluent, easy-to-use API for common use cases:

// Create a new diagram
const kit = PlantKit.create('diagram-name', 'Diagram Title');

// Add elements (chainable)
kit.addElement(id, type, label, properties?);

// Add relationships (chainable)
kit.addRelation(fromId, toId, relationType, label?);

// Get element for hierarchies or advanced manipulation
const element = kit.getElement(id);

// Configure diagram (chainable)
kit.setScale(1.5);
kit.setLayout('top to bottom direction');
kit.addInclude('./custom.puml');

// Generate output
const plantuml = kit.generate();

// Access underlying objects for advanced use
kit.diagram  // Access Diagram instance
kit.graph    // Access ElementGraph instance
kit.getElement(id)  // Retrieve element by ID

Example - Complete Workflow:

const output = PlantKit.create('architecture', 'System Architecture')
  .addElement('frontend', 'Application_Component', 'Web Frontend')
  .addElement('backend', 'Application_Component', 'API Backend')
  .addElement('database', 'Technology_Node', 'Database')
  .addRelation('frontend', 'backend', 'Rel_Flow', 'API calls')
  .addRelation('backend', 'database', 'Rel_Access_rw', 'reads/writes')
  .setScale(1.2)
  .generate();

Example - With Hierarchies:

const kit = PlantKit.create('hierarchy', 'Business Capabilities');

// Add elements
kit.addElement('business', 'Grouping', 'Business Layer')
   .addElement('marketing', 'Strategy_Capability', 'Marketing')
   .addElement('sales', 'Strategy_Capability', 'Sales');

// Build hierarchy using getElement
const parent = kit.getElement('business');
const marketing = kit.getElement('marketing');
const sales = kit.getElement('sales');

if (parent && marketing && sales) {
  parent.addChild(marketing);
  parent.addChild(sales);
}

const output = kit.generate();

Example - Advanced Configuration:

const kit = PlantKit.create('custom', 'Custom Diagram');

// Use fluent API
kit.addElement('e1', 'Business_Actor', 'Actor')
   .addElement('e2', 'Business_Process', 'Process');

// Access diagram for advanced features
kit.diagram.addInclude('./Archimate.puml');
kit.diagram.setLayout('top to bottom direction');

// Access graph for queries
const relations = kit.graph.getOutgoingRelations(someElement);

const output = kit.generate();

Element Class

// Create hierarchical element structures
const parent = new Element('System', { type: 'Application_Component' });
const child = new Element('Module', { type: 'Application_Component' });
parent.addChild(child);

// Navigate and query
parent.getChildren();           // Get all children
parent.findElement('Module');   // Find by name recursively
parent.removeChild('Module');   // Remove child by name

ElementGraph Class

// Manage semantic relationships
const graph = new ElementGraph();
graph.addNode(elementA);
graph.addNode(elementB);
graph.addRelation(elementA, elementB, 'Rel_Flow', { label: 'data' });

// Query relationships
graph.getOutgoingRelations(elementA);  // Get outgoing relations
graph.getIncomingRelations(elementB);  // Get incoming relations
graph.getConnectedNodes(elementA);     // Get all connected nodes

Diagram Class

// Configure diagram output
const diagram = new Diagram('my-diagram', 'My Architecture');
diagram.setScale(1.5);
diagram.setLayout('top to bottom direction');
diagram.addInclude('archimate-theme.puml');

// Auto-generate sprites
diagram.autosprite('Business_Actor');
diagram.autosprite('Rel_Flow');

// Generate output with legends
const plantuml = diagram.output();

PlantKit Utilities

const plantkit = new PlantKit();

// Convert elements to ArchiMate syntax
plantkit.toArchimate(element);              // Element tree to PlantUML
plantkit.toArchimateRelations(graph);      // Relations to PlantUML
PlantKit.toValidElementName('My Element'); // Generate valid IDs

// Debug output
plantkit.printNode(element);               // Print element tree
plantkit.printArchimate(element);          // Print ArchiMate syntax

Model Validation

The facade validates registered ArchiMate types and generated PlantUML aliases. Call validate() to inspect model diagnostics before rendering; generate() rejects a model that has diagnostics.

const kit = PlantKit.create('business-model', 'Business Model')
  .addElement('customer', 'Business_Actor', 'Customer');

const diagnostics = kit.validate(); // [] for a valid model
const plantuml = kit.generate();

Advanced Features

Automatic Sprite Management

// Automatically generates sprites and legends
diagram.autosprite('Business_Process');
diagram.autosprite('Rel_Realization');

// Results in:
// sprite $Business_Process_Sprite jar:archimate/business-process
// legend with sprite documentation

Type-Safe ArchiMate Generation

// Type-safe element creation
const element = ArchimateElement(
  ArchimateElement.type.Business_Actor, 
  'CUST_001', 
  'Customer'
);

// Type-safe relationship creation
const relation = ArchimateRelation(
  ArchimateRelation.type.Rel_Flow_Down,
  'SRC_001',
  'TGT_001',
  'data flow'
);

Validation and Error Handling

// ElementGraph validates relationships
try {
  graph.addRelation(nodeA, nodeB, 'Rel_Flow');
} catch (error) {
  // Throws if nodes aren't in the graph
  console.error('Both nodes must be added to graph first');
}

Examples

Comprehensive example files demonstrate real-world usage:

• sample01.mts - Complete business capability model with multiple layers and relationships
• sample02.mts - CSV data import and process modeling example

You will need to run the support.sh script to have the relevant tools ready to check the output.

Running Examples

# Build the library
npm run build

# Examples use the published API
# Refer to examples for implementation patterns

Use Cases

PlantKit is ideal for:

• Enterprise Architecture Documentation - Model business, application, and technology layers
• System Integration Planning - Visualize data flows and dependencies
• Business Process Modeling - Document workflows and stakeholder interactions
• Technology Roadmaps - Plan implementation phases and deliverables
• Automated Documentation - Generate diagrams from data sources (databases, APIs, etc.)

Output Quality

PlantKit generates production-ready PlantUML with:

• ✅ Proper ArchiMate Syntax - Compliant with ArchiMate 3.x specifications
• ✅ Clean Formatting - Readable, well-structured PlantUML code
• ✅ Sprite Integration - Automatic icon management and legends
• ✅ Scalable Output - Configurable sizing and layout options
• ✅ Include Support - Integration with external PlantUML themes and libraries

TypeScript Support

Full TypeScript support with:

• Complete type definitions for all classes and functions
• IntelliSense support in modern IDEs
• Compile-time validation of ArchiMate element and relationship types
• Generic type support for properties and metadata

Contributing

We welcome contributions to PlantKit! Whether you're fixing bugs, adding features, improving documentation, or sharing examples, your help is appreciated.

Please read our Contributing Guide for details on:

• Development setup and workflow
• Coding standards and best practices
• Testing requirements
• Pull request process

Quick Links:

• Report a Bug
• Request a Feature
• View Open Issues

License

PlantKit is licensed under the MIT License. See LICENSE.md for details.

Made with ❤️ for the Enterprise Architecture community