koriym / app-state-diagram
An Application Diagram Generator
Maintainers
Package info
github.com/alps-asd/app-state-diagram
Language:TypeScript
pkg:composer/koriym/app-state-diagram
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
This package is auto-updated.
Last update: 2026-06-12 01:59:11 UTC
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/2.x/docs/demo/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
This repository includes .mcp.json for MCP clients. It starts the ALPS MCP server with:
{
"command": "npx",
"args": ["-y", "@alps-asd/mcp"]
}
See AI Integration Guide and MCP Server README for Claude Code, Claude Desktop, and other AI tools.
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