3 posts tagged with "architecture"

The onboarding doc says "check the architecture diagram" and the architecture diagram shows a monolith from 2023 that the team decommissioned in the spring. Nobody is lying — the draw.io file lives on one person's laptop, and the wiki holds a screenshot nobody owns. An architecture that only exists as a static export rots silently, because the thing you would edit is invisible to review.

Quick answer: document system architecture in Confluence as Mermaid text — C4Context for the system in context, architecture-beta for the deployment, block-beta for the topology you want laid out precisely — rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Every level stays an editable code block, so the wiki's architecture changes in the same review that changes the system. This post gives you three copy-paste examples.

Your team grows by two people. The new hires open the wiki and find the architecture doc: a screenshot of a whiteboard, dated 14 months ago, where PaymentService does everything except the thing the diagram says OrderService does. Day-1 onboarding just taught two people the wrong architecture.

Quick answer: keep the architecture in Confluence as a Mermaid class diagram, rendered by Mermaid Plus Diagrams & AI Agent for Confluence and diffs like code. Classes, methods, interfaces, ownership — in editable text that updates when the code does. This post gives you three copy-paste examples: the onboarding service map, interface+implementation modules, and a request-flow sketch.

Every architecture review ends the same way: the team sketches a system on a whiteboard, someone takes a blurry phone photo, and the diagram is never seen again. The next sprint a new engineer joins, asks how the system fits together, and the whiteboard gets redrawn from memory — different every time.

The fix is to capture the architecture sketch on the ticket it describes, editable by anyone on the team, versioned with the issue. That's what Excalidraw Diagrams plus Whiteboards for Jira does: it adds a full drawing canvas to every Jira issue, with 229 bundled shape libraries and freehand drawing. The same experience is available in Confluence via Excalidraw plus Whiteboards for Confluence. This guide walks through running an architecture session that produces a saved, shareable diagram.