Docs

Architecture

What this screen is for

Architecture Explorer draws your catalog as a graph: systems, components, APIs and resources, with the relationships between them. It is the answer to “what talks to what, and what breaks if this goes away” — a question the Catalog list can hold the data for but cannot show you.

The page describes itself as a technical architecture dossier, and that is the right way to use it: something you read before changing a shared component, and something you export into a design review.

Before you start

To do this You need
Open the page catalog read access

The graph is built from the catalog, so it only shows what is registered there. Register your systems and components in Settings › Development › Projects first — an unregistered component is invisible here, which reads as “nothing depends on it”.

Opening it

  1. Explore › Architecture in the sidebar.

Direct URL: /architecture

The interface

📸 Screenshot Placeholder: Architecture Explorer showing a system with its components and APIs. Mark: (1) the search field, (2) the kind filters with their counts, (3) the relation filters, (4) the Owner and System selectors, (5) the Legend, (6) Export, (7) Refresh.

# Control What it does When you’d use it
1 Search Filters the graph by name Finding one node in a large estate
2 Kind filters Toggles systems, components, APIs, resources — each showing a count Cutting the graph down to what you care about
3 Relation filters Shows or hides relationship types Tracing one kind of dependency at a time
4 Owner / System Narrows to one team or one system Reviewing a single team’s surface
5 Legend What each node shape and colour means The first time, and whenever you forget
6 Export Saves the current view as an image Design reviews, incident write-ups
7 Refresh Re-reads the catalog After registering something new

The counts on the kind filters are worth reading on their own. A system with forty components and two APIs is shaped differently from one with four components and thirty APIs, and you can see that before drawing anything.

Walkthroughs

Find what depends on a component

  1. Explore › Architecture.
  2. Search for the component.
  3. Turn off the kinds you do not care about, so the graph stops competing for attention.
  4. Use the relation filters to show one relationship type at a time. Everything at once is a hairball; one relation at a time is a diagram.

Review one team’s surface

Set the Owner filter to their group. What you get is everything that team is responsible for — useful in a handover, and uncomfortable in a good way when a team discovers what it actually owns.

Export a view

Filter down to what you want to say, then Export. Exporting the unfiltered graph produces something nobody reads.

Scenario

Deciding whether a shared library can be changed.

Someone proposes a breaking change to a component several teams use. The question is not “is the change good” but “who finds out the hard way”.

  1. Explore › Architecture, search for the component.
  2. Turn off resources and APIs first, leaving systems and components. You want the shape before the detail.
  3. Read which systems reach it. Note the Owner on each — those are the people who need to know, and they are frequently not the people in the conversation.
  4. Turn the relation filters on one at a time. A direct dependency and a transitive one call for different conversations.
  5. Cross-check against Deploy: a dependent system that has not deployed in months is a different risk from one that ships daily.
  6. Export the filtered view and attach it to the proposal. An argument about blast radius goes much faster with a picture than without.

The caveat to state out loud in step 3: this graph shows what is registered. A consumer nobody added to the catalog does not appear, and its team will still be broken. Treat the graph as a floor on the blast radius, not a ceiling.

When it doesn’t work

Symptom Cause How to check Fix
A component you expect is missing It is not registered in the catalog Projects Register it, then Refresh
The graph is an unreadable hairball Too many kinds and relations shown at once The filters Filter to one relation type; hide kinds you do not need
Nothing has an owner The systems have no owning group Projects Set owners on the systems
A dependency you know exists is not drawn The relationship is not recorded in the catalog The component’s catalog entry Add the relation to its entity
The graph looks stale It reflects the catalog at load time — Refresh
Export is empty or huge It exports the current view The filters Filter first, then export

Next