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.

Configuration Properties

version

numberRequired

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

Example

targets

arrayRequired

A list of conversion targets.

Supported Formats

Mermaid

Fully supported for both Automation (CI/CD) and Live Preview.

.mmd.mermaid

PlantUML

Supported for Automation and transformation pipelines.
(Note: Live Preview in the browser is currently limited to Mermaid.)

.puml.plantuml.pu

Polagram Documentation