Diagrams forget what your system is

Why there is another notation for software architecture, and what it refuses to do.

Every team has the picture. Boxes for services, a cylinder for the database, arrows with "HTTPS" written on them, a dashed frame around "the platform". It lives in Confluence, in a .drawio file, in a Mermaid block in a README. It was right when it was drawn.

Then a service is split, a queue is added, the payments database gets its own team, and the picture is wrong — not dramatically, just enough that nobody trusts it, and the person who knows the real shape is asked to explain it in a meeting. Again.

Pictures cannot be checked

The problem is not the tool. Mermaid, PlantUML, draw.io, Excalidraw — all of them draw shapes. A rounded rectangle labelled "Checkout" is a rounded rectangle; the tool does not know it is a service, that it exposes an API, that it writes one database and reads another, or that it runs as three pods in prod and one in stage. So nothing can be checked against the picture: not a pull request, not the running system, not a rule like "no service writes a store it does not own".

The standards that could be checked describe systems in depth — one interface at a time. OpenAPI knows every endpoint of one service. AsyncAPI knows every message on one channel. A .proto file knows one gRPC contract; a migration file knows one schema; Terraform knows one environment. Nothing describes a system in breadth: what exists, how it connects, where it runs — in a form a machine can read and a person can diff.

What ArchCode is

A text notation for exactly that breadth, and nothing deeper. Three lines are a useful document:

service   checkout   "Checkout"      tech Go
datastore orders_db  "Orders DB"     tech PostgreSQL 16

checkout writes orders_db over SQL

archcode: "0.2"
objects:
  - id: checkout
    kind: service
    name: Checkout
    attrs:
      tech: [Go]
  - id: orders_db
    kind: datastore
    name: "Orders DB"
    attrs:
      tech: [PostgreSQL, "16"]
relations:
  - from: checkout
    verb: writes
    to: orders_db
    over: SQL
placements: []

{
  "archcode": "0.2",
  "objects": [
    {
      "id": "checkout",
      "kind": "service",
      "name": "Checkout",
      "attrs": {
        "tech": [
          "Go"
        ]
      }
    },
    {
      "id": "orders_db",
      "kind": "datastore",
      "name": "Orders DB",
      "attrs": {
        "tech": [
          "PostgreSQL",
          "16"
        ]
      }
    }
  ],
  "relations": [
    {
      "from": "checkout",
      "verb": "writes",
      "to": "orders_db",
      "over": "SQL"
    }
  ],
  "placements": []
}

service and datastore are kinds, not shapes — the renderer decides that a datastore is a cylinder and sits beside the service that owns it. writes is a verb, not an arrow — a verb is what a rule can reason about. over SQL is a fact about the relation. There are no coordinates: layout is computed, and a person pins a position only when they mean it.

Contracts stay where they live. checkout exposes http openapi://checkout.yaml @9f3c records the fact of a contract, its address and its revision; the grammar has no place to copy a path or a field into. That is the whole trick: ArchCode holds what the depth standards cannot, and points at them for everything they can.

What it refuses to do

Compete with the depth standards. No endpoints, no fields, no schemas. If you find yourself wanting to write them, you want OpenAPI, and ArchCode wants a pointer to it.

Store layout as architecture. Coordinates exist only inside a view block, only when a human pinned them, and a file without one still renders. Two people describing the same system should produce the same file.

Draw the picture for you to admire. The picture is a projection of the model — one lens shows what talks to what, another shows where it runs, a third sums what it needs. Drag a card in the Playground and the text changes, by one line.

Bend. Seven design rules, and they do not.

Where it stands

Version 0.2 is a draft with a reference engine, a Playground and a conformance suite; every section of the specification says whether it is implemented, partial, reserved for 0.3 or planned. The language is CC BY 4.0, the tooling Apache-2.0, and there will be no change of either — that decision was made once, before the first commit.

If you have a system to write down, the Quickstart takes five minutes. If you have a Structurizr workspace, most of it carries over. If the notation gets in your way, that is the feedback we are after.

ArchCode is an open standard created and maintained by Baryshev Labs.