Polagram - Interactive Sequence Diagrams

Overview

Introduction

Polagram is a sequence diagram transformation engine designed for complex systems. It helps you maintain a single source of truth while generating clarity for every context.

The Problem: One Size Doesn't Fit All

Sequence diagrams are a powerful tool for visualizing systems, but a single diagram rarely satisfies everyone's needs. The "optimal" level of detail depends entirely on your role:

For Developers: Details like error handling, retry logic, and authentication flows are critical for implementation.
For Product Managers: These technical details are noise. They need to see the high-level user journey and happy paths to understand the feature.
For QA Engineers: They might need to focus exclusively on specific failure scenarios or edge cases.

Traditionally, this forces a choice: maintain one giant, unreadable diagram, or manually keep multiple diagrams in sync—a recipe for documentation drift. Polagram solves this by dynamically generating all these views from a single source of truth.

One Diagram. Every View.

Polagram treats diagrams like code. Instead of maintaining multiple fragmented diagrams manually, you maintain one master diagram and use Lenses to generate specific views.

master.mmd

Source

polagram.yml

Lens for Developers

Lens for PMs

Lens for QA

Lenses

diagram.dev.mmd

diagram.pm.mmd

diagram.qa.mmd

Optimized Views

The Power of Lenses

Don't just take our word for it. Lenses allow you to transform a complex master diagram into specific views for every stakeholder.

Try applying different lenses to the complex diagram below. Notice how the internal logic changes based on the audience.

Live Demo: Context Switching

See how the same diagram looks to different team members.

⚡️ Master Diagram

The raw, single source of truth containing all logs, errors, and details.

Raw View

Why Polagram?

Focus Mode

Instantly extract the lifecycle of a specific service.

Noise Reduction

Filter out messages or participants using Regex.

Fragment Resolution

Unwrap complex alt or loop blocks.

Client-Side

Runs entirely in the browser using the library.

Getting Started

Installation

Install the Polagram CLI globally or as a development dependency in your project.

npm install -g @polagram/cli
# or
pnpm add -g @polagram/cli

Quick Start

Create a polagram.yml configuration file to define your diagram targets and transformations.

polagram.yml

version: 1
targets:
  - input: ["diagram.mmd"]
    outputDir: "generated"
    lenses:
      - name: clean-view
        layers:
          # A comprehensive lens example
          
          # 1. Hide the Logger participant (Remove)
          - action: remove
            selector:
              kind: participant
              name: Logger
              
          # 2. Focus only on critical path participants (Focus)
          - action: focus
            selector:
              kind: participant
              name: API
              
          # 3. Simplify success scenarios (Resolve)
          - action: resolve
            selector:
              kind: fragment
              condition:
                pattern: "Success:.*"

Then run the CLI to generate your diagrams:

polagram generate

CLI Options

Customize the execution with the following options:

-c, --config <path>

Specify the path to the configuration file. Defaults to polagram.yml in the current directory.

POLAGRAM_CONFIGEnv Var

Alternative way to specify the config file path via environment variable.

CI/CD Integration

Polagram is built for automation. Generate up-to-date diagrams on every commit using GitHub Actions or your preferred CI provider.

.github/workflows/diagrams.yml

name: Generate Diagrams
on: [push]
jobs:
  diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
      - name: Install Polagram
        run: pnpm add -g @polagram/cli
      
      - name: Generate Diagrams
        run: polagram generate
      
      - name: Upload Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: diagrams
          path: generated/

Reference

Specification

Detailed reference for the polagram.yml configuration file. The file format is YAML.

Root Object

versionnumberRequired

The version of the configuration schema. Currently, only version 1 is supported.

targetsTarget[]Required

A list of conversion targets. Each target defines inputs, output location, and transformations.

Target

inputstring[]Required

Array of file paths or glob patterns to include.

Example: ["src/**/*.mmd"]

outputDirstringRequired

Directory where generated files will be saved.

ignorestring[]

Array of glob patterns to exclude from processing.

lensesLens[]Required

List of lenses (transformations) to apply to the input diagrams.

Lens

namestringRequired

Unique name for the lens. Used in the filename suffix (e.g., .web-view.mmd).

layersLayer[]Required

Ordered list of transformation layers. Applied sequentially.

Layer

action'focus' | 'remove' | 'resolve'Required

The operation to perform on the selected elements. Each action only supports specific selector kinds.

focus

Keeps only interactions involving the selected participants.

Selectors:participant

remove

Removes the selected elements (participants, messages, or groups).

Selectors:participantmessagegroup

resolve

Unwraps specific branches of fragments (alt, opt, loop).

Selectors:fragment

selectorSelectorRequired

Defines which elements to target. The valid fields depend on the `kind` of selector.

Selector

Specifies the criteria for selecting elements. All string matching is exact by default. Use an object with pattern for Regex.

Common Fields

kind'participant' | 'message' | 'fragment' | 'group'Required

The type of element to select.

Kind-Specific Fields

kind: participant

name (Matcher): Filter by participant name.
id (Matcher): Filter by participant ID (alias).
stereotype (Matcher): Filter by stereotype (e.g. <<Service>>).

kind: message

text (Matcher): Filter by message content.
from (Matcher): Filter by Sender ID.
to (Matcher): Filter by Receiver ID.

kind: fragment

condition (Matcher): Filter by branch condition text (e.g. "Success").
operator (string | string[]): Filter by loop/alt type.

Type Definitions

Matcher = string | { pattern: string, flags?: string }

Coming Soon

PlantUML Support

We are currently developing support for PlantUML diagrams. Soon you will be able to apply the same powerful transformations to your existing PlantUML files (.puml).

In Development

Polagram Documentation