payments.topos.yaml
element: payments-api
dimension: application
layer: logical
relations:
- serves: checkout-web
- reads: ledger-storeToposML
What Topos derives
- A schema-validated model, checked in CI before it lands
- A traversable graph projection you can query
- Rendered views, with layout decoupled from the model
The problem
Architecture knowledge is scattered across whiteboards, slide decks, and diagramming tools that drift out of date the moment they are saved. There is no single trustworthy description of how a system is designed — one a person can read, a tool can validate, and a renderer can draw.
How Topos works
A Topos model is plain YAML in git. It is reviewed in merge requests, diffed like any other change, and validated against a formal schema before it lands. Relationships between elements carry meaning rather than being lines on a canvas, so the model can be projected into a graph and traversed.
The part that matters most is what it refuses. An element cannot declare its own dimension or layer — its kind carries them, once, in the catalog — and the server validates a change before it commits it, rejecting anything that does not conform. The store cannot hold an invalid model.
Where it actually is
Topos is the earliest of our three products and we would rather say so than imply otherwise.
What exists and runs: a catalog of 36 element kinds and 17 relationship types, a two-phase validator, a graph projection with impact and trace queries, a web studio, and to-be scenarios that can be forked, compared against the current state, and promoted. It models our own mahjong platform together with the Kubernetes cluster that platform runs on — 152 elements and 257 relationships in a single identity space.
What does not exist yet: the conceptual layer, and the strategy and motivation kinds. Both are on the roadmap, and until they land, Topos cannot model the top of an enterprise architecture. If that is what you need today, it is not ready for you.
Every element sits on a two-axis grid, which is what makes a model multi-perspective instead of one flat diagram:
- Dimensions — what you are describing: business, information, application, technology.
- Layers — how abstract the description is: conceptual or logical.
Elements are defined once and reused as a shared inventory across projects.
Visualisation is a projection
Rendering is decoupled from the model. Layouts are stored separately, so how a diagram looks never contaminates what the model means, and the same source can be drawn several ways for several audiences.
Who it is for
Architects, developers, and DevOps, platform and infrastructure engineers — anyone who writes, reviews, or operates systems and needs the description to stay true.