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 npm

npm install -g @alps-asd/app-state-diagram

Try It

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

CLI Options

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

Option	Description
-o, --output <file>	Output file path
-f, --format <format>	Output format: html (default), svg, dot, mermaid
-w, --watch	Watch mode with live reload
--port <port>	CDP port for watch mode (default: 9222)
--label <mode>	Label mode: id (default) or title
--validate	Validate ALPS profile only
-e, --echo	Output to stdout

Subcommands

asd merge <base.json> <partial.json>  # Merge partial ALPS into base profile

Watch Mode

Start watch mode with automatic Chrome launch and live reload:

asd -w profile.json

Chrome opens automatically with remote debugging enabled. Changes to the ALPS file trigger instant browser refresh.

Validation

The validator checks for errors, warnings, and suggestions:

• Errors (E001-E011) - Missing id/href, missing rt, invalid type, broken references, duplicate ids, etc.
• Warnings (W001-W004) - Missing title, naming conventions (go*/do* prefixes), orphan descriptors
• Suggestions (S001-S003) - Consider adding doc/title to improve documentation

See Validation Issues Reference for detailed explanations and how to fix each issue.

asd profile.json --validate

Examples

See live demos or visit app-state-diagram.com

Mock Generation

Generate a browsable HTML mock site from an ALPS profile. Every CSS class in the HTML is an ALPS descriptor ID — zero presentation classes. Switch between bare HTML, wireframe, and production quality by changing one CSS file.

alps.xml → html/ + css/level{1,2,3}.css + api/ + i18n/

See AI Integration Guide for setup (requires alps2mock skill).

Design Application with AI

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

Documentation

• Quick Start Guide
• Official Documentation

Related Projects

• ALPS Specification
• asd-action - GitHub Action for CI/CD
• alps-skills - ALPS skills for Claude Code
• alps-skeleton-xml - ALPS skeleton (XML)
• alps-skeleton-json - ALPS skeleton (JSON)

License

MIT