README

app-state-diagram is a tool that visualizes state transitions and information structures of RESTful applications. It generates interactive state diagrams and hyperlinked documentation from ALPS (Application-Level Profile Semantics) profiles written in XML or JSON.

Key Benefits

Application Overview: Visually grasp complex RESTful applications and understand the big picture
Clear Information Semantics: See how data flows and what each element means
Enhanced Team Communication: Both technical and business teams can discuss using the same visual representation
Design Consistency: Represent application structures uniformly and discover design issues early

Information Architecture Perspective

app-state-diagram embodies the three key aspects of Information Architecture (IA):

Ontology: Defines the semantic meaning of application elements and their relationships
Taxonomy: Organizes information into structured hierarchies and classifications
Choreography: Describes interaction patterns and rules for state transitions

By focusing on these IA principles, app-state-diagram helps create a shared understanding of application semantics across organizational boundaries, independent of specific implementation technologies.

Quick Start

Online Editor (No Installation)

https://editor.app-state-diagram.com/

Rendering Quality

Local Installation: When Graphviz (dot command) is installed locally, app-state-diagram provides high-quality rendering with improved font metrics, especially for Japanese text
Online Editor: Uses JavaScript-based rendering which may have some limitations in font rendering quality
Automatic Detection: The tool automatically detects available rendering engines and uses the best option available

Install with Homebrew

brew install alps-asd/asd/asd

After installation, run:

asd --watch path/to/your/profile.json

CLI Usage

Basic usage:

asd path/to/your/profile.json

Options

--mode=html|markdown|svg: Set output mode (default: html)
```
asd --mode=html profile.json      # Generate interactive HTML (default)
asd --mode=markdown profile.json  # Generate markdown documentation
asd --mode=svg profile.json       # Generate SVG diagrams for embedding
```
SVG mode generates two standalone SVG files:
- profile.svg - Main diagram with descriptor IDs
- profile.title.svg - Diagram with human-readable titles
Perfect for embedding in documentation, presentations, or web pages.

--watch or -w: Enable watch mode with live browser sync

asd --watch profile.json          # Start development server
asd --watch --port=3001 profile.json  # Custom port

--port: Set development server port (default: 3000, only with --watch)
```
asd --watch --port=8080 profile.json
```

Examples

See these live demos:

Documentation

For more details, please refer to:

koriym / app-state-diagram

Maintainers

Details