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

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

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, 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).

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.