Writing on architecture documentation
Depth for the engineers who own system design. No fluff.
Docs that stay current
Why architecture documentation rots, and how to keep it honest.
Architecture as code
C4, diagrams-as-code, and documenting systems engineers actually maintain.
Building a hosted MCP server for architecture docs
A request-bound MCP server, OAuth with PKCE, and YAML compilation through the existing document services, including the limits of validation.
The C4 model in practice
Separate system context from container detail, use a copyable YAML example, and review the diagram for responsibilities the schema cannot check.
ERDs and sequence diagrams as code
Copy valid YAML for typed entities and an ordered login exchange, then review the schema and failure paths that syntax alone cannot verify.
Forking Excalidraw for structured diagrams
How structured ERD and API cards share geometry across editing and export, and why sequence diagrams use a separate element.
Why I built Archdocs
I wanted shared services to keep their identity across architecture diagrams, with YAML and a canvas editing the same document.
The real cost of stale documentation
Stale architecture docs never show up as a line item, but they tax onboarding, incidents, design, and audits. Here is a framework for naming those hidden costs so you can justify fixing them.
Architecture decision records, a practical guide
How to write architecture decision records your team will actually maintain, including a copyable template and a worked example you can paste into your repo today.
Your architecture diagrams are lying to you
Architecture diagrams go stale the moment they are drawn. Here is why they drift, the three ways they fail, and what actually keeps them honest.