Skip to content

v0.1.0

Release Date: 2026-04-15

Initial release of system-spec: a Go-native system topology specification for modeling microservices, infrastructure, and connectivity.

Highlights

  • Go-native specification - Strongly-typed Go structs as source of truth
  • Multi-cloud support - AWS, GCP, Azure, and Cloudflare resource bindings
  • Multi-format rendering - D2, Mermaid, Cytoscape.js, Sigma.js, GraphViz DOT
  • Graphize integration - Provider for code knowledge graph databases

Core Specification

System Types

Type Description
System Root type with services, owners, networks, deployments
Service Microservice with image, repo, connections, endpoints
Connection Service-to-service connectivity with port and protocol
Endpoint Exposed port/protocol for a service
Owner Team ownership with contact details

Cloud Resource Bindings

Provider Resources
AWS RDS, DynamoDB, SQS, SNS, S3, Bedrock
GCP CloudSQL, PubSub, GCS
Azure CosmosDB, ServiceBus, BlobStorage
Cloudflare Workers, R2

Generic Resources

Provider-agnostic resource types for portability:

  • Database - SQL/NoSQL databases
  • Queue - Message queues
  • Storage - Object/blob storage
  • Cache - Caching layers
  • LLM - AI/ML model endpoints

Deployment Mappings

Tool Support
Helm Chart references with service mapping
Terraform Module references with resource mapping

CLI Commands

# Validate a system spec
system-spec validate system.json

# Render to various formats
system-spec render system.json --format d2
system-spec render system.json --format mermaid
system-spec render system.json --format cytoscape
system-spec render system.json --format sigma
system-spec render system.json --format dot

# Generate JSON Schema
system-spec schema

# Convert to graph representation
system-spec graph system.json

Rendering Formats

D2

Text-based diagramming with automatic layout:

system-spec render system.json --format d2 > system.d2
d2 system.d2 system.svg

Mermaid

GitHub-compatible flowcharts for documentation:

system-spec render system.json --format mermaid

Output can be embedded directly in GitHub Markdown.

Cytoscape.js

Interactive web visualization:

system-spec render system.json --format cytoscape > graph.json

Sigma.js

Optimized for large graph visualization:

system-spec render system.json --format sigma > graph.json

GraphViz DOT

Classic graph description for PDF/PNG export:

system-spec render system.json --format dot > system.dot
dot -Tpng system.dot -o system.png

Go SDK

import (
    "github.com/plexusone/system-spec/spec"
    "github.com/plexusone/system-spec/graph"
    "github.com/plexusone/system-spec/render"
)

// Load and validate
sys, err := spec.LoadFromFile("system.json")
if err != nil {
    log.Fatal(err)
}

// Convert to graph
g := graph.FromSystem(sys)

// Render to D2
renderers := render.NewRenderers()
output, err := renderers.D2.Render(g)

Graphize Integration

system-spec includes a provider for graphize knowledge graphs:

import (
    "github.com/plexusone/graphize/provider"
    _ "github.com/plexusone/system-spec/graphize" // Register provider
)

The provider:

  • Auto-detects system-spec JSON files
  • Creates service nodes with svc: prefix
  • Creates resource nodes (database, queue, storage)
  • Links services via connects_to edges
  • Maps services to repos via links_to edges

Example

See payments-system.json for a complete example demonstrating:

  • Multiple microservices with connections
  • AWS resources (RDS, SQS, S3)
  • Team ownership
  • Helm deployment mappings