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>

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

• AI Integration Guide
• MCP Server
• 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