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

Installation

Add to your Gemfile:

gem 'archsight'

Or install directly:

gem install archsight

Quick Start

# 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.

CLI Commands

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

Analysis as Typst

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.

Web Server Options

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

Option	Description
-r, --resources PATH	Path to resources directory
-p, --port PORT	Port to listen on (default: 4567)
-H, --host HOST	Host to bind to (default: localhost)
--production	Run in production mode (quiet startup)
--disable-reload	Disable the reload button in the UI
--enable-logging	Enable request logging (default: false in dev, true in prod)
--inline-edit	Enable inline editing to save directly to source files

Features

MCP Server

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.

Web Interface

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)

Resource Editor

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

Validation

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

Documentation

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

Guide	Description
Modeling Guide	How to model architecture using resource types and relations
Query Language	Full query syntax reference for searching resources
Computed Annotations	Aggregating values across relations
ArchiMate Reference	ArchiMate concepts and mapping
TOGAF Reference	TOGAF alignment and concepts
Diagrams	.asd diagram DSL and the archsight diagram command
Architecture	Technology stack and directory structure
Configuration	The configuration file and environment variables (tokens, URLs)
Docker	Running Archsight in Docker
Kubernetes	Helm chart deployment guide

Architecture

See Architecture for the technology stack and directory structure.

Contributing

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

License

Apache 2.0 License. See LICENSE.txt for details.