koriym/app-state-diagram

An Application Diagram Generator

v0.14.1 2025-08-07 11:29 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

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/

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:

• Book Store
• LMS

Documentation

For more details, please refer to:

• Quick Start Guide
• Official Documentation