In my previous post, I shared how I built tooling to eliminate context-switching in my Solutions Architect role. But the real transformation came from rethinking how I approach the work itself — using AI not just to track what I do, but to amplify how I think about systems.
This post explores the foundational principles that make AI-augmented solutions architecture possible: treating documentation and diagrams as code, structured for both human and machine consumption.
The Problem with Traditional SA Workflows
Every Solutions Architect knows this cycle: you receive a feature request, dive into the requirements, consult stakeholders, make decisions, and produce documentation. But between the thinking and the delivery, there’s a mountain of boilerplate:
- Structuring solution documents
- Drawing diagrams from scratch
- Formatting ADRs consistently
- Maintaining visual standards across artifacts
By the time the scaffolding is complete, your mental energy for actual architecture work is depleted. This isn’t a productivity issue — it’s a workflow design problem. The craft of producing documentation consumes the craft of architecture.
The Vision: AI as Your Architecture Assistant
AI tools have reached a point where they can reliably handle structured, repetitive work — if given the right structure to work from. The insight is this: if your solution documents always follow the same template, and your diagrams always follow the same design language, an AI can produce a credible first draft of both.
The SA’s job becomes direction and decisions — not document production. The goal isn’t to finish faster, but to think more deeply with the same time budget. Spend time solutioning, not pixel-pushing.
Pillar 1: Docs as Code
What “Docs as Code” Means
In this approach, documentation is written in plain text Markdown with a defined, consistent structure — the same discipline engineers apply to writing code.
It doesn’t mean replacing your documentation platform. Confluence (or similar) remains the official home of solution documents. What changes is how you produce those documents.
The workflow becomes:
Draft locally in Markdown → Publish to documentation platform
(AI assistant + templates) (copy-paste)
The local Markdown files are your working drafts — the surface where AI does the heavy lifting. The platform is where finalized documents live.
Why Markdown for Drafting
| Property | Benefit |
|---|---|
| Plain text | AI tools read and write it natively — no conversion needed |
| Structure-preserving | Headings, tables, and code blocks are explicit |
| Platform-compatible | Copy-paste into documentation editors works seamlessly |
| Portable | Readable in any editor or viewer |
| Always current | AI assistants work directly on the file |
The critical advantage: Markdown is machine-readable by default. When an AI opens a Markdown file, it sees structured content with explicit headings and sections — not a blob of formatted text.
The Structure Principle
The most important rule: every document of the same type must have the same structure.
This isn’t about aesthetics — it’s about making AI output predictable and useful.
When prompted correctly, an AI can:
- Read requirements you’ve pasted or referenced
- Open a template to understand the required structure
- Draft a populated document with all required sections, placeholder content for SA input
- Generate diagrams using a consistent design language
The SA’s job after this: fill in the actual decisions, validate interpretations, add nuance.
Solution Documents
A solution document template covers:
| Section | What goes here |
|---|---|
| Overview | Initiative name, SA, summary, risk score |
| Context | Problem statement, requirements, capabilities affected, system context diagram, scope |
| Key Architecture Decisions | Table of decisions, each linked to an ADR |
| Solution Design | Logical architecture, core design content, business rules, integration flows, data model, APIs |
| Review History | Date, outcome, reviewer notes |
Diagrams are PlantUML files in a diagrams/ subfolder, embedded via include for local preview, pasted inline when publishing.
Architecture Decision Records (ADRs)
ADRs document single architectural decisions: what was decided, why, what was considered and rejected, consequences.
ADRs serve three purposes:
- At writing time: forces thinking through options, not just asserting conclusions
- At review time: gives reviewers enough context to approve with confidence
- After delivery: future engineers understand why the system is the way it is
Lifecycle: PROPOSED → ACCEPTED → (eventually) DEPRECATED
ADRs are never deleted. A superseded ADR is a record that the decision once existed and was intentionally replaced.
Pillar 2: Diagrams as Code
Why Diagrams as Code
Traditional diagramming tools are visual-first. They work for ad-hoc whiteboarding but have problems for structured SA workflows:
- Inconsistency by default. Every person makes different choices — colors, shapes, fonts, arrow styles.
- Not AI-friendly. An AI can’t generate or modify a proprietary file.
- Hard to review changes. Binary or XML files are opaque.
Diagrams as code solves this. Changes that used to take hours now take seconds. You spend time solutioning, not pixel-pushing.
The Toolset
PlantUML is the primary tool. It covers all diagram types:
- Sequence diagrams (most common for integration flows)
- Context diagrams (stakeholder-facing overview)
- Logical architecture diagrams (components, queues, databases)
- Physical diagrams (infrastructure deployment)
PlantUML files (.puml) are plain text, AI-readable, and supported in documentation platforms via macros.
The Design Language
The diagram design language is the single source of truth for all visual decisions:
- Semantic color palette — colors encode ownership and system type, not aesthetics
- Shape-to-role mapping — specific shapes and stereotypes for each role
- Canvas and connector settings — font size, arrow thickness, background color
- Layout conventions — when to use different orientations, how to control density
- Title conventions — exact format for each diagram type
- Starter templates — copy-paste-ready code
The Design Language as an AI Prompt Anchor
This is the key to consistent AI-generated diagrams.
An AI has no inherent knowledge of your conventions. Left to its own defaults, it produces inconsistent output. But when given the design language as context, it produces conformant output on the first pass.
The prompt pattern:
Using the [diagram type] design block from the design language guide,
generate a [diagram type] for the following:
[describe systems, actors, and flows]
Without this anchor, AI falls back to defaults. With it, output conforms to your standards.
What This Approach Is Not
It is not lazy work
This approach raises the quality bar. A structured ADR with explicit options analysis is more rigorous than a narrative paragraph. A consistent diagram is more defensible than an ad-hoc one.
The SA still owns:
- Defining problems correctly
- Consulting the right people before involving AI
- Evaluating trade-offs
- Making and recording every decision
- Reviewing and correcting every piece of AI output
- Signing off on final documents
AI handles scaffolding. The architect handles substance.
It does not replace human knowledge
No AI tool has the institutional context that colleagues carry. The engineers who built systems know things not in any document. System owners understand unrecorded constraints. Product owners know what business actually needs versus what requirements say.
This is why consulting people comes before AI research. Humans first, AI second.
It is not tool-dependent
The approach works with any AI assistant that can read a folder of files. The value is in the structure and workflow — not specific tools.
The Core Insight: Consistency Enables Automation
The reason AI-augmented workflows fail is inconsistency. If every project has different document structures, different diagram styles, different naming — the AI has nothing to anchor on. It produces generic output requiring more rework than starting from scratch.
The foundations — Docs as Code and Diagrams as Code — exist to create enough consistency that AI output is immediately usable, not just a starting point.
| If you standardize… | Then AI can… |
|---|---|
| Document structure (solution template, ADR template) | Draft 70–80% of a solution doc from requirements in a single pass |
| Diagram style (design language, color palette, stereotypes) | Generate syntactically correct, visually consistent diagrams from descriptions |
| Folder structure (predictable layout) | Navigate and cross-reference any document without being told where things are |
| Prompting patterns (reusable recipes) | Produce consistent output across engagements |
Guiding Principles
- Humans first, AI second. Consult people before AI. AI fills gaps; it doesn’t replace experts.
- Structure is a prerequisite for automation. You can’t automate what’s inconsistent.
- Templates are contracts. Every template defines what must be present in every document. AI and humans are held to the same contract.
- The design language is the single source of truth. Any diagram that deviates is technical debt.
- AI drafts; SA decides. AI handles structure and boilerplate. The SA owns every decision and rationale.
- Always triple-check AI output. AI surfaces options you didn’t think of — verify surprises with people or docs before accepting.
- Never ship without reviewing. Always human-in-the-loop. AI assists, you decide.
In the next post, I’ll cover how to organize your work with proper folder structures and master templates that make this all work together.