Archsight

Bringing enterprise architecture into focus.

Ruby gem for visualizing and managing enterprise architecture documentation using YAML resources with GraphViz visualization. Inspired by ArchiMate 3.2.

Service view	Artifact view

Add to your Gemfile:

gem 'archsight'

Or install directly:

gem install archsight

# Start web server (looks for resources in current directory)
archsight web

# Start with custom resources path
archsight web --resources /path/to/resources

# Or use environment variable
ARCHSIGHT_RESOURCES_DIR=/path/to/resources archsight web

Access at: http://localhost:4567

Also available as Docker image and Helm chart.

archsight web [OPTIONS]      # Start web server
archsight lint               # Validate YAML and relations
archsight import             # Execute pending imports
archsight analyze            # Execute analysis scripts (--format typst -o out.typ for Typst source)
archsight template KIND      # Generate YAML template for a resource type
archsight diagram FILE.asd   # Render a diagram DSL file to SVG
archsight console            # Interactive Ruby console
archsight version            # Show version

archsight analyze --format typst [-o report.typ] [-f REGEX] [-v] writes the results of all (or the filtered) analyses as one Typst document instead of the terminal rendering: a summary, a section per analysis with its tables, lists, text and messages, and asd code sections as inline SVG diagrams. Without -o the source goes to stdout; paste it into typst.app or run typst compile report.typ. -v keeps all rows (otherwise tables and lists are cut after 10) and the error backtraces.

--template layout.typ replaces the built-in layout with your own. The document then imports the template and calls two functions it must define: archsight-report as a show rule (count, passed, failed, findings), and analysis-result(name:, description:, state:, duration:, data:)[body] once per analysis, where body is the rendered sections and data is a dictionary of what the script passed to data(key, value). data sections appear only here (not in the web UI or terminal), so a script can hand structured values (for example a matrix) to a template while keeping its tables for the web. With a template, tables and lists are never cut.

archsight web [--resources PATH] [--port PORT] [--host HOST]
              [--production] [--disable-reload] [--enable-logging]
              [--inline-edit]

The tool includes an MCP (Model Context Protocol) server that enables AI assistants to query and analyze the architecture data programmatically.

Start the server:

archsight web

Add to Claude Code:

claude mcp add --transport sse ionos-architecture http://localhost:4567/mcp/sse

For a deployed server use its address, for example claude mcp add --transport sse archsight https://archsight.example.com/mcp/sse. The MCP endpoint accepts any hostname, like the web UI and the API, and has no authentication of its own: if the ingress requires a token, pass it with --header "Authorization: Bearer <token>". The ingress must not buffer or time out the long-lived SSE connection.

Available tools:

• query - Search and filter resources using the query language
• analyze_resource - Get detailed resource information and impact analysis
• resource_doc - Get documentation for resource kinds

Export to Confluence: archsight export --to confluence publishes pages to the Confluence page they link to, with images, diagrams and draw.io, views and requirements as tables, and refuses to overwrite edits made in Confluence unless --force (Wiki pages).

Macros such as {status:yellow WIP} and {emoticon:2705} work inline in pages (Wiki pages).

Views and analyses can be embedded in pages with ![[View/Name]] / ![[Analysis/Name]] (Wiki pages); a view can also be written in place with a ```view block (inline views), and the requirements of a selection of resources shown with a ```requirements block (requirements).

Images and draw.io diagrams are plain files in the resources directory and are embedded in markdown with relative paths (![](../img/a.png), ![](../../fop/flow.drawio)); only files of image, draw.io and .asd diagram types inside the resources directory are served, through /api/v1/assets/. The draw.io viewer (Apache-2.0) ships with Archsight and loads nothing from other hosts, see Wiki pages.

Wiki pages are resources of the kind Page, so the same tools reach them, for example Page: page/tags == "howto" or, for full-text search, Page: page/content =~ "kubernetes" (a bare word only matches names). See Pages and AI assistants.

Browse & Search:

• Browse resources by type (Products, Services, Components, Requirements, etc.)
• Search by name or tag using the query language
• Filter by annotations (quality attributes, status, frameworks)

Visualization:

• Interactive GraphViz diagrams showing relationships
• Zoom/pan controls for large diagrams
• Hand-drawn .asd diagrams via the architecture/diagram annotation or ```asd blocks in markdown
• Dark mode support
• Layer-based color scheme (Business, Application, Technology, Data)

Create and edit resources through the web interface:

Edit existing resource:

• Navigate to any resource detail page
• Click the "Edit" button (only available for non-generated resources)
• Modify annotations and relations
• Generate YAML and copy to clipboard

Create new resource:

• Go to any kind listing (e.g., /kinds/ApplicationComponent)
• Click "New" button
• Fill in required fields
• Add relations using cascading dropdowns
• Generate YAML and copy to clipboard

The editor supports:

• Type-aware form fields (dropdowns for enums, number inputs, URL validation)
• Markdown textarea for descriptions
• Relation management with cascading dropdowns
• Validation before YAML generation
• One-click copy to clipboard

Validate YAML syntax and verify all relationship references:

archsight lint

Checks:

• YAML syntax correctness
• Resource kind definitions exist
• All relation references point to existing resources
• Prevents broken links between resources

Detailed documentation is available in the web interface under the Help menu:

See Architecture for the technology stack and directory structure.

See CONTRIBUTING.md for development setup, code style guidelines, and pull request process.

Apache 2.0 License. See LICENSE.txt for details.