systemspec-architecture

README

Systems Architecture Spec (SAS)

A statically-typed-friendly, Go-first specification for describing software systems as semantic graphs: nodes, typed relationships, boundaries, identities, entitlements, and protocol bindings.

Architecture is a typed graph with properties and constraints; diagrams are views over that graph.

Primary responsibility

The primary responsibility of this project is the semantic model itself — a spec whose typed graph carries enough meaning that machines can reason over an architecture without human interpretation. Diagrams, threat modeling, launch readiness, and change analysis are use-case requirements: they determine what semantics the core must express and prove the model works in practice, but they are consumers of the spec, not the spec.

If a use case needs something the model can't express, the model changes. If only one use case wants something, it belongs in a consumer, a profile, or a namespaced extension — never in the core.

Status

v0.2. The core semantic model, validation engine, three renderers, technology catalogs, PIDL protocol bindings, the Threat Model Spec bridge, and assurance coverage reporting are implemented and dogfooded end to end. v0.2 adds a semantic diff engine (typed ChangeSet with change-impact classification and a Baseline/Assessment/ChangeReview model), a FedRAMP change-assessment profile, and container/sandbox node and boundary kinds for K8s-native topology. See SPEC.md for the normative specification and docs/specs/initiatives/INIT-SYSTEMSARCHITECTURESPEC-001/ for the PRD, TRD, PLAN, and ROADMAP.

Packages

Package	Responsibility
sas	the core semantic graph — Architecture, Node, Relationship, Boundary, Identity, Entitlement, View, ProtocolBinding, Assurance, Extensions
validate	referential-integrity checks plus profile-conditional rules (development, deployment, security, threat-model, sre)
render	shared rendering foundation (node grouping, shape/label mapping) used by every renderer
render/mermaid, render/d2, render/dot	view → diagram renderers, each verified against the real mmdc/d2/dot compilers
catalog	AWS/GCP/Kubernetes technology display data and HTTP/SQL/MCP operation mappings
bridge/threatmodel	exports an Architecture as the system-under-analysis for Threat Model Spec, verified against its real JSON Schema
diff	semantic diff engine — typed ChangeSet, change-impact classification, and the Baseline/Assessment/ChangeReview model
diff/fedramp	FedRAMP change-assessment profile — three-outcome classification with control-mapping hooks
assure	assurance-reference coverage reporting (tests, metrics, detections, deployment)
cli	business logic shared by every CLI command
cmd/sas	thin Cobra adapter over cli
schema	generated, embedded JSON Schema (//go:embed), linted with schemakit --property-case camelCase
ts	generated Zod/TypeScript types, conforming to the same fixture corpus as the Go model

CLI

sas validate <architecture.json> [--profile development,deployment,security,threat-model,sre] [--format console|json]
sas view <architecture.json> [--view <id> | --group-by --include-kinds --include-relations --include-boundaries] --format mermaid|d2|dot
sas bind <architecture.json> --pidl <protocol.json> [--format console|json]
sas export threat-model <architecture.json>
sas assure <architecture.json> [--format console|json]

sas validate --profile security is the launch-readiness gate: run it before a system with internet-facing traffic goes to production (see SPEC.md §10.1).

Example

examples/dogfood/acme-widgets.json is a fictional storefront (browser actor, API, orders database, payment provider, GitHub OAuth login) exercising the full field surface — boundaries, views, a PIDL binding, and launch-readiness-clean relationships:

go run ./cmd/sas validate examples/dogfood/acme-widgets.json --profile security
go run ./cmd/sas view examples/dogfood/acme-widgets.json --view context --format d2

Design principles

• Statically Typed Friendly. Go structs are the source of truth. JSON Schema is generated (never hand-written) and stays within the PlexusOne static-type profile: no oneOf / anyOf / allOf, no schema composition. Explicit discriminated fields instead of unions. TypeScript/Zod conform downstream. JSON is the interoperability contract — it never becomes a second type system.
• Views are queries, not files. One canonical model produces development, deployment, security, and threat-model projections without semantic drift. Renderers (Mermaid, D2, Graphviz DOT) are adapters, never sources of truth.
• Profiles, not levels. Semantics are optional in the core and required only by the profile that needs them, so a minimal architecture file stays minimal.
• Core ontology, not a technology catalog. "AWS Lambda" is not a core type — it's kind: compute.function + technology: {provider: aws, service: lambda}. Concrete vendor semantics live in catalogs outside the core schema.
• Integration layer, not universal schema. SAS binds to specialized specs by reference — PIDL for protocol choreography, Threat Model Spec for risk reasoning, Multi-Agent Spec for agent definitions — rather than absorbing them.

License

MIT — see LICENSE.