system-spec

System Spec

A Go-native system topology specification for modeling microservices, infrastructure, and connectivity.

Features

• 🔒 Strongly-typed - Go structs are source of truth; no interface{} or any
• 📄 JSON-first - JSON format with generated JSON Schema
• 🔗 Graph-aware - Services as nodes, connections as edges
• ☁️ Multi-cloud - AWS, GCP, and Cloudflare resource bindings
• 🎨 Multi-render - D2, Mermaid, Cytoscape.js, Sigma.js, GraphViz

Installation

CLI

go install github.com/plexusone/system-spec/cmd/system-spec@latest

Go SDK

go get github.com/plexusone/system-spec@latest

Quick Start

Create system.json:

{
  "name": "my-system",
  "services": {
    "api": {
      "image": { "name": "myorg/api", "tag": "v1.0" },
      "repo": { "url": "https://github.com/myorg/api" },
      "connections": {
        "database": { "port": 5432, "protocol": "sql" }
      }
    },
    "database": {
      "image": { "name": "postgres", "tag": "15" }
    }
  }
}

Validate and render:

# Validate
system-spec validate system.json

# Render to D2
system-spec render system.json --format d2 > system.d2
d2 system.d2 system.svg

# Render to Mermaid (GitHub-compatible)
system-spec render system.json --format mermaid

# Render to Cytoscape.js (web visualization)
system-spec render system.json --format cytoscape > system.json

Go SDK Usage

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
renderers := render.NewRenderers()
output, err := renderers.D2.Render(g)

Specification

The human-readable spec (spec.md) is for developers. The JSON Schema is for tools and AI agents.

Supported Resources

Cloud Providers

Deployment Tools

Rendering Formats

Design Principles

1. Go-first: Go structs → JSON Schema (not the reverse)
2. No polymorphism: map[string]Service not map[string]interface{}
3. Schema validation: Must pass schemalint
4. Graph-native: Built for visualization and dependency analysis

Documentation

• Full Documentation (MkDocs)
• Getting Started
• CLI Reference
• Go SDK
• Examples

Project Structure

system-spec/
├── spec/           # Core Go types (System, Service, etc.)
├── graph/          # Graph representation and conversion
├── render/         # Multi-format renderers
├── schema/         # JSON Schema generation
├── cmd/system-spec/# CLI tool
├── versions/       # Versioned specs and schemas
│   └── v0.1.0/
│       ├── spec.md              # Human-readable
│       └── system.schema.json   # Machine-readable
├── docs/           # MkDocs documentation
└── examples/       # Example system specs

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run go test ./... and golangci-lint run
5. Submit a pull request

Changelog

See CHANGELOG.md for release history.

Generated from CHANGELOG.json using structured-changelog.

License

MIT License - see LICENSE for details.