Architecture Graph

The graph format

A project's architecture lives in one authored file, usually architecture/graph.yaml, and an ag.config.json, usually at the repository root, says where it is. Everything AG generates (guidance, indexes, summaries) is derived from that one file.

The smallest complete graph

A graph has a schema version, an ID, a title, a description, nodes and relationships. Every record has a status and a list of references; proposed records may have none. This example passes ag validate; the site build checks it.

schemaVersion: "1"
id: graph:greeter
title: Greeter architecture
description: A command-line greeter. Covers who decides the greeting wording.
nodes:
  - id: component:formatter
    kind: component
    name: Formatter
    description: Builds the greeting text from a name and a tone.
    status: proposed
    references: []
  - id: capability:greet
    kind: capability
    name: Greet a person
    description: Produce a greeting for a named person.
    status: proposed
    references: []
relationships:
  - id: relationship:formatter-owns-greet
    kind: owns
    from: component:formatter
    to: capability:greet
    description: Wording changes belong in the formatter, not in the interface that prints it.
    status: proposed
    references: []

Configuration

The configuration names the graph and the folder for generated output. References in the graph are paths relative to the folder that holds the configuration.

{
  "configVersion": "1",
  "graph": "architecture/graph.yaml",
  "generated": "architecture/generated"
}

Contract sidecars

A contract, data_object or artifact node can reference a JSON Schema for its data and example payloads that must match it. Sidecars arrive in the next release. See contract schemas and examples and the specification.

Reference and schemas