Flowmapper

1. Overview

Flowmapper is a diagramming tool that allows you to write data flow diagrams as declarative code. The tool generates interactive or static SVG flowmaps from code. Flowmapper allows complex architectures to be composed from smaller "flows" as directed graphs, making it easier to focus on individual flows within a larger system.

Flowmapper is an npm package and can be installed via npm. The tool can also be run using npx.

npm install flowmapper
flowmapper --help
## or 
npx flowmapper --help

3. Writing Flow Diagrams

Flow diagrams are written using a superset of the standard Graphviz Dot syntax. This language is intuitive and easy to learn. Here's an example of how to structure your flow diagrams:

# File structure 
basic
├── backend.dot
├── frontend.dot
└── infrastructure.dot

And the corresponding Dot syntax:

// backend.dot
digraph Backend {
  apiGateway -> authentication [label="Auth/Token" dir="both"];
  apiGateway -> backendServices [label="Route/Response" dir="both"];
  backendServices -> database [label="DB Query/Result" dir="both"];
}
// frontend.dot
digraph Frontend {
  browser -> frontendApp [label="Web Request/Response" dir="both" fminit="source"];
  frontendApp -> apiGateway [label="API Request/Response" dir="both" fminit="source"];
}
// infrastructure.dot
digraph Infrastructure {
  subgraph cluster_cloud {
    margin=25;
    label="Cloud Infrastructure";
    apiGateway;
    authentication;
    backendServices;
    database;
    subgraph cluster_storage {
      label="Storage";
      database;
      storageService;
      s3Bucket;
      database -> storageService [
        label="Backup",
        fmi="sink",
        fmdt="batch"
      ];
      storageService -> s3Bucket [label="Store" fmdatatransfer="microbatch"];
    }
  }
}

4. Running Flowmapper

Flowmapper can be run directly in a browser. The tool converts the provided .dot files and renders them as interactive SVG diagrams in a Sveltekit app. It can then be hosted as a static website.

5. Hosting Diagrams

Flowmapper includes a CLI option to publish your diagrams as a GitHub page. The CLI also provides a local server for live previews during the creation workflow.

6. Interacting with Flowmaps

Consumers can interact with the Flowmaps by clicking on individual Nodes and Edges. A unique feature of Flowmapper is the ability to "filter" a single flow within the architecture. This leads to a UI render where the architecture is blurred out, with just the selected flow in focus.

7. Git Operations

The .dot files used in Flowmapper are easy to commit to a git repository, making version control and collaboration straightforward.

Flowmapper is a developer-focused tool for visualizing and merging data flow diagrams. It uses the Graphviz DOT language to create and manipulate flow diagrams, and it provides a simple, intuitive interface for combining and customizing these diagrams.

Features

• Parse and render DOT files as SVG
• Merge multiple flow diagrams into a single diagram
• Preserve node and edge attributes during merge
• User-friendly interface for developers

Installation

To get started with Flowmapper, you'll need to clone the repository and install the dependencies:

  git clone https://github.com/cloud-on-prem/flowmapper.git
  cd flowmapper
  npm install
  npm run dev

This will launch the development server at localhost:5173. Open this URL in your browser to view and interact with Flowmapper.

To build the application for production, run:

  npm run build

This will generate an optimized build in the dist folder.

Contributing

Contributions are welcome! If you'd like to contribute to Flowmapper, please follow these steps:

1. Fork the repository
2. Create a new branch for your feature or bugfix
3. Make your changes and commit them to your branch
4. Push your changes to your fork
5. Create a pull request for your changes
6. Please ensure that your code follows the project's coding style and that all tests pass before submitting a pull request.

License

Flowmapper is released under the MIT License. See LICENSE for more information.