koriym/app-state-diagram

An Application Diagram Generator

0.17.0 2025-12-12 08:09 UTC

Requires

• php: ^8.1
• ext-dom: *
• ext-filter: *
• ext-json: *
• ext-libxml: *
• ext-mbstring: *
• ext-simplexml: *
• koriym/data-file: ^1.0
• michelf/php-markdown: ^1.9
• seld/jsonlint: ^1.8
• symfony/polyfill-php81: ^1.31

Requires (Dev)

• bamarni/composer-bin-plugin: ^1.4
• phpunit/phpunit: ^9.6.10
• rector/rector: ^1.1

MIT

• Akihito Koriyama

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

Quick Start

Online Editor (No Installation)

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

Install with Homebrew (Recommended)

brew install alps-asd/asd/asd

Auto-updates with brew upgrade.

Install with Composer

Prerequisites: PHP 8.1+, Composer

composer require koriym/app-state-diagram

Try It

curl -O https://raw.githubusercontent.com/alps-asd/app-state-diagram/master/docs/bookstore/alps.xml
asd alps.xml  # or ./vendor/bin/asd for Composer
open index.html # on macOS

CLI Options

asd [options] <profile.json|profile.xml>

Option	Description
--mode=html	Generate interactive HTML (default)
--mode=markdown	Generate markdown documentation
--mode=svg	Generate SVG diagrams for embedding
--watch, -w	Enable watch mode with live browser sync
--port=N	Set development server port (default: 3000)

SVG mode generates two standalone SVG files:

• profile.svg - Main diagram with descriptor IDs
• profile.title.svg - Diagram with human-readable titles

Tip: Install Graphviz (dot) for better multibyte character rendering.

Examples

See these live demos:

• Demos

Design Application with AI and IA

See AI Integration Guide for setting up Claude Code, MCP Server, or other AI tools.

Documentation

• Quick Start Guide
• Official Documentation