Discuss the Architecture Where It Lives

Someone notices that Billing writes straight to the ledger database, although ADR-12 says only the Ledger API may. They ask in a Slack thread. Two replies, a "good catch, I'll look", and the thread has scrolled out of view by lunchtime. A month later the arrow is still on the diagram, ADR-12 still reads as if nobody ever questioned it, and the person who said "I'll look" has moved to another team. The question was asked and answered, somewhere the architecture can't see.

That is the gap we worked on this week. On October 18 we shipped six features that move the conversation about the architecture into the model itself: comments pinned on the diagram, @mentions, # citations with a "Cited in" list, link previews in the app and in Slack, following, and tasks. Each one attaches a discussion to the element, decision or page it is about, and all of them report to the inbox we added on October 10.

The same question, asked in the model

Here is that ledger question again, run through what shipped. The names and the project are examples. The behavior is the product's.

Marie pins it where she sees it. She is reviewing the Checkout project at container level. She presses C, the cursor becomes a crosshair, and she clicks the arrow from Billing to Ledger DB. A comment box opens halfway along the relationship, and she writes:

Billing writes to Ledger DB directly here. #ADR-12 says ledger writes
go through the Ledger API. @Sam, is this still intended?

Typing # opened a list of the project's elements, decisions and pages, and ADR-12 became a chip that opens the decision. Typing @ listed the people who can open the project, and Sam, who owns Billing, became a chip too. She presses ⌘ Enter. The bubble gets a number, #7, and everyone who opens that view of the diagram sees it.

Sam is told. His bell shows that Marie mentioned him, with her comment as the excerpt. He doesn't have to be watching the diagram, or the right Slack channel, to find out.

The answer becomes a task. Sam replies that it is a leftover from the ledger migration and he will move it behind the Ledger API. Marie, who started the discussion, gets his reply in her inbox. She opens the full discussion, clicks Task under Sam's reply, assigns it to him, picks Friday as the due date and clicks Create task. A checkbox appears under the reply, and the task lands in the To do tab of Sam's inbox.

The decision remembers it was questioned. Open ADR-12 and the bottom of its expanded card now lists Marie's comment under Cited in, with the text around the citation. Whoever reads the decision next learns that the database it protects was still being written to, and can click through to the discussion.

The fix announces itself. Sam replaces the arrow through a change request. Its description cites #ADR-12 and pastes the link to discussion #7, which shows as a preview card under the text. Everyone who can edit the project is told a change request was opened, as before. Léa, from the finance data team, can't review it, but she follows the Checkout project, so she gets a line too: a change request opened in a followed project notifies the followers who can't review it.

The loop closes. Sam ticks the task. Marie, who created it, is told "Sam completed a task you created". She resolves #7 and the bubble disappears from the diagram. When Sam drops the change request link into #payments, the Archyl bot unfurls it with its title, status and project.

Every piece of that exchange is attached to something in the model: the relationship, the decision, the owner, the change request. Nothing depends on someone remembering where a thread was.

What each feature does

Comments on the diagram

Press C, or click Comment in the bar at the bottom of the diagram, then click where the comment belongs:

  • on empty space, the bubble stays at that spot;
  • on an element, it is attached and follows the element when it moves, and the discussion also appears in the element's details panel;
  • on a relationship, it sits halfway along it.

Bubbles are numbered per project and keep the same size at any zoom. Each belongs to the level and view where it was placed, so a comment on the system context doesn't show up inside a system. Resolved bubbles are hidden; tick Show resolved in comment mode to see them greyed out. Otherwise a pinned discussion is an ordinary discussion: it is listed with the project's discussions, and its replies notify the people in it. Docs: Comments on the diagram.

@mentions

Type @ in a comment or a reply, in the context, decision or consequences of an ADR, in a documentation page, or in a change request description, comment or review. The list shows the people who can open the project and the teams that have at least one of them. Mentioning a team reaches its members who can open the project.

People are told once: editing the text again doesn't notify anyone already mentioned. Mentions in a title aren't detected, so write them in the body. When we shipped the inbox, mentions were the first thing on its "doesn't do yet" list. They are in now. Docs: Mentions, citations and links.

# citations and "Cited in"

Type # in the same places to cite a system, container, component or code element (each shown with its parent), a decision (listed as ADR-3 with its title), or a documentation page. Clicking the chip opens what it cites. An element opens in the diagram at its own level, already selected.

The other half is the backlink. Every element, decision and page lists where it is cited, newest first, with the excerpt around each citation: in the Cited in section of an element's details panel, at the bottom of a decision's expanded card, at the bottom of a page. This is the part a Slack thread can't give you. The conversation points at the ADR, and the ADR points back.

Link previews, in Archyl and in Slack

Copy link sits on an element's details panel, on each decision card and at the top of each documentation page. An element link opens the element at its level, selected. Change requests and discussions are shared from the address bar.

Paste an Archyl link into a comment, a change request description or a review and it shows as a card under the text: title, type and status, project and an excerpt. Up to three links per message are previewed, and only for people who can open the project. Everyone else sees a plain link.

In Slack, the bot now unfurls links to a project, an element, a decision, a documentation page, a change request or a discussion into the same preview. It follows the rules the bot already had. The preview is built with the permissions of the admin who connected the workspace, only for projects of the organization the workspace is connected to, and in a scoped channel a link to a project outside the scope stays plain. A link to something that doesn't exist, or that the bot can't see, also stays plain, so a preview never confirms that a page exists. Docs: Link previews in Slack.

Following

Follow an element, a decision or a whole project with the bell in the element's details panel, on the decision card, or in the diagram toolbar. A filled bell means you follow. The owners of an element follow it without doing anything, and so do the members of a team that owns it. Click the bell to opt out and Archyl remembers, even though you still own the element.

Followers hear when what they follow is changed or deleted (the notification lists the fields that changed), when a followed element gets a comment, and when a change request touches a followed element. Project followers also hear when an element, a decision or a page is added. Following doesn't grant access: lose access to the project and the notifications stop. Docs: Following.

Tasks

Under any comment or reply in a project, click Task, pick an assignee among the people who can open the project (you, by default), optionally a due date, and click Create task. A comment carries one task at most. The task shows under its comment with a checkbox, the assignee, and the due date, which turns red once it has passed. Removing the task keeps the comment.

Your open tasks are in the To do tab of the inbox, soonest due first, with a count on the tab. Each element's details panel has a To do section listing the tasks from all its discussions. The assignee is told when a task is created for them or reassigned to them, and the creator is told when someone else completes it. Docs: Tasks.

Agents can tag too

Coding agents connected through the MCP server write in the same model: they open change requests, record decisions, leave comments. Until now, an agent writing "@Sam, can you confirm?" produced plain text that told nobody.

Now the server reads what an agent writes the way the pickers do in the app. In a comment, an ADR, a documentation page or a change request:

  • @Name mentions a person or a team, who is told in their inbox like any other mention. The agent can call list_mentionables to get the exact names.
  • #Label cites a C4 element, a decision (#ADR-12) or a page, which then lists the agent's text under Cited in.

A comment posted by an agent also reaches the people already in the discussion and the followers of the element, as one posted by a person does. Each write tells the agent what was linked, so it can check that @Sam really reached Sam.

Agents can read the links back, too. get_backlinks returns where an element, a decision or a page is cited. Before touching Ledger DB, an agent can find Marie's comment #7 and the change request that cited ADR-12, instead of rediscovering the question.

Following without drowning

Following pulls against the rule we set for the inbox: it holds only what waits on you or answers something you did. A followed element changing doesn't wait on you. We let it in because you asked for it, by clicking the bell or by owning the element, and we put limits on how loud it can get:

  • Moving an element or changing its style notifies nobody.
  • Several edits to the same thing within an hour make one notification, as long as you haven't read it.
  • If you follow a project but not the element, you get at most one notification of each kind per hour for that project. Approving an AI discovery that creates hundreds of elements is one line, not hundreds.
  • You aren't told twice. A comment that mentions you, or a reply in a discussion you are part of, reaches you through that notification only.
  • You are never told about your own actions.

If you want every change across the organization, email notifications and the History page are still the place for it.

What it doesn't do yet

  • Inbox only. Mentions, follows and tasks don't send email.
  • No reminder on due dates. An overdue task turns red, and nothing pings you.
  • No list of what you follow. You manage it from each element, decision or project. A documentation page can't be followed on its own; follow its project instead.
  • Bubbles stay where you put them. You can't move one once placed. A relationship's bubble sits at the midpoint between its two elements, not on the curve of the line. Bubbles are hidden while Time Travel is open.
  • No previews in Microsoft Teams. Slack only, for now. Slack workspaces connected before October 18 need to be connected again from Organization → Bot to grant the two new permissions, links:read and links:write.
  • Agents can't see tasks, follows or pins. Through the MCP server they can mention and cite, but not yet read or complete tasks, follow an element or pin a comment on the diagram.
  • No tasks outside a project. Organization discussions can't carry one.

Try it

Open a diagram, press C, and click the relationship you've been meaning to ask about. Mention whoever owns the other end and cite the decision it's supposed to follow. The docs cover each piece in detail:

Related reading: an inbox for what waits on you, for the rules every notification above follows, and scoping the bot per channel, for what a Slack channel is allowed to preview.