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.
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 webAccess at: http://localhost:4567
# Run web server (default)
docker run -p 4567:4567 -v "/path/to/resources:/resources" ghcr.io/ionos-cloud/archsight
# Run lint
docker run -v "/path/to/resources:/resources" ghcr.io/ionos-cloud/archsight lint -r /resources
# Run any command
docker run ghcr.io/ionos-cloud/archsight versionAccess web interface at: http://localhost:4567
Notes:
- Volume mount
-v "/path/to/resources:/resources"mounts your resources directory - Default command starts the web server on port 4567
- Pass subcommands directly (lint, version, console, template)
archsight web [--resources PATH] [--port PORT] # Start web server
archsight lint [--resources PATH] # Validate YAML and relations
archsight template KIND # Generate YAML template for a resource type
archsight console [--resources PATH] # Interactive Ruby console
archsight version # Show versionThe tool includes an MCP (Model Context Protocol) server that enables AI assistants to query and analyze the architecture data programmatically.
Start the server:
archsight webAdd to Claude Code:
claude mcp add --transport sse ionos-architecture http://localhost:4567/mcp/sseAvailable tools:
query- Search and filter resources using the query languageanalyze_resource- Get detailed resource information and impact analysisresource_doc- Get documentation for resource kinds
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
- Dark mode support
- Layer-based color scheme (Business, Application, Technology, Data)
Validate YAML syntax and verify all relationship references:
archsight lintChecks:
- 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:
| 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 |
- Web Framework: Sinatra
- Templating: Haml
- Styling: Pico CSS v2.x
- Interactivity: HTMX
- Icons: Iconoir (1,671+ icons)
- Visualization: GraphViz (@hpcc-js/wasm for client-side SVG)
archsight/
├── exe/archsight # CLI executable
├── lib/
│ ├── archsight.rb # Entry point
│ └── archsight/
│ ├── cli.rb # Thor CLI
│ ├── configuration.rb # Resources path config
│ ├── database.rb # YAML loader and validator
│ ├── query/ # Query language (lexer, parser, evaluator)
│ ├── resources/ # Resource types (20+)
│ ├── annotations/ # Annotation modules
│ ├── mcp/ # MCP server tools
│ └── web/ # Sinatra app, views, assets
│ └── doc/ # Documentation (markdown)
└── test/ # Test suite
See CONTRIBUTING.md for development setup, code style guidelines, and pull request process.
Apache 2.0 License. See LICENSE.txt for details.