How to Create an Interactive Architecture Diagram From a YAML File

The goal: go from a list of your services to a filterable, interactive dependency graph running on your own infrastructure. No backend, no database, no SaaS account. Here’s the complete walkthrough.

Step 1: Define Your YAML Schema

Start with the minimal schema that captures what matters. For most teams, that’s five fields per service:

services:
  - name: api-gateway
    description: Public-facing API entry point, routes to internal services
    team: platform
    stack: [Node.js, nginx]
    status: active
    depends_on:
      - auth-service
      - user-service
      - payments-service

  - name: auth-service
    description: Authentication and session management
    team: platform
    stack: [Go, Redis]
    status: active
    depends_on:
      - user-service

  - name: payments-service
    description: Payment processing and billing
    team: commerce
    stack: [Python, PostgreSQL]
    status: active
    depends_on:
      - fraud-detection
      - notification-service

Field guidelines:

• name: unique identifier, kebab-case by convention
• description: one sentence, in plain English
• team: the team that owns this service (used for filtering)
• stack: language(s), framework(s), and datastore(s) (used for filtering)
• status: active, deprecated, or migrating
• depends_on: list of service names this service calls directly

Step 2: Validate the YAML

Before building the visualization, validate that every service listed in depends_on exists as a named service. Missing nodes create broken edges in the graph and are easy to catch with a simple lint script:

python3 - <<EOF
import yaml
with open('services.yaml') as f:
    data = yaml.safe_load(f)
names = {s['name'] for s in data['services']}
deps = {d for s in data['services'] for d in s.get('depends_on', [])}
missing = deps - names
if missing:
    print('Missing service definitions:', missing)
else:
    print('All dependencies resolve correctly.')
EOF

Step 3: Build the Visualization Layer

The visualization layer reads the YAML and renders an interactive graph using a library like Cytoscape.js or D3.js. Key features to implement:

• Auto-layout: position nodes automatically (dagre or cose-bilkent layout algorithms work well)
• Hover-trace: on node hover, highlight upstream and downstream dependencies, dim others
• Filter controls: filter by team, status, or tech stack
• Shareable URLs: encode the current filter state in the URL so views can be linked

Step 4: Deploy as Static Files

The output is a static HTML/CSS/JS bundle. Deploy it to any static hosting provider:

# Netlify
ntl deploy --prod --dir=dist

# GitHub Pages
gh-pages -d dist

# AWS S3
aws s3 sync dist/ s3://your-bucket --delete

On every YAML update: rebuild and redeploy. The diagram reflects the new state in seconds. No server restart, no cache invalidation, no database migration.

Skip the Build — Use Service Map

If you want the result without building the visualization layer from scratch, Service Map is a pre-built implementation of exactly this pattern — YAML in, interactive dependency graph out, deployable to any static host. €99 one-time, includes auto-layout, hover-tracing, filter controls, and shareable URLs.