Tech Design Doc

Tech Design Doc — Confluence Publishing Workflow

Overview

End-to-end workflow for creating production-quality technical design documents: codebase exploration, spec writing in markdown, Mermaid diagram generation, Confluence publishing with rich macros, multi-round review cycles, and implementation planning with checkpoints.

When to Use

• User asks to create a design doc, HLD, LLD, spec, or RFC
• User wants to publish a technical document to Confluence
• User needs diagrams (flowcharts, sequence diagrams, state machines) in a doc
• User asks to "put this on Confluence" or "make this look good on Confluence"
• User wants to create an implementation plan from a spec
• User says "design this feature" or "write a spec for this"

Core Workflow (7 Phases)

Phase 1: Explore → Phase 2: Design → Phase 3: Diagrams → Phase 4: Publish →
Phase 5: Review → Phase 6: Fix → Phase 7: Implementation Plan

Phase 1: Explore the Codebase First

Never design in a vacuum. Before writing a single line of spec, understand the existing system.

1. Spawn an Explore agent to map the current architecture — entities, managers, controllers, consumers, SFN definitions, DB schema
2. Identify integration points — what services does this system already talk to? What patterns does it use?
3. Read the existing enums, factories, base classes — your design must follow existing conventions
4. Check Flyway migration numbering — what's the next available version?
5. Map the existing data flow — which tables are read/written at each step?

Output: A mental model of the system you're designing into. Quote file paths, class names, patterns.

Phase 2: Write the Spec (Local Markdown)

Write the spec as a local .md file first. This is the source of truth. Confluence is just the rendered view.

SPEC_FILE="${REPO_ROOT}/FEATURE_NAME_SPEC.md"

Spec structure — battle-tested order:

Key principles:

• Every status needs a transition map — from, to, trigger, actor, terminal?
• Every API needs request + response — even internal ones
• Every DB change needs exact DDL — not "add a column", but ALTER TABLE x ADD COLUMN y VARCHAR(255)
• Every config needs a default — never leave it as "TBD"
• Every external call needs error handling defined — what happens on failure?

Phase 3: Generate Diagrams with Mermaid

Use mmdc (mermaid-cli) to render diagrams locally as PNG. Never use Mermaid macros on Confluence — most instances don't have the app installed.

# Install if needed
npm install -g @mermaid-js/mermaid-cli

# Render with high quality
mmdc -i diagram.mmd -o diagram.png -w 1400 -b transparent --scale 2

Which diagram type for what:

Color palette for consistent diagrams:

Green   #4CAF50  → success, start, complete, approved
Red     #f44336  → failure, terminal, rejected, error
Orange  #FF9800  → warning, lapse, timeout
Blue    #2196F3  → decision points, choice states
Lt Blue #E3F2FD  → wait states, paused
Lt Green #E8F5E9 → active processing steps
Pink    #FCE4EC  → urgent/immediate actions
Grey    #F5F5F5  → background for subgraphs

Styling example:

graph TD
    START([Start]) --> step1[Processing Step]
    step1 --> decision{Decision?}
    decision -->|YES| success[Success]
    decision -->|NO| failure[Failure]
    
    style START fill:#4CAF50,color:#fff
    style success fill:#4CAF50,color:#fff
    style failure fill:#f44336,color:#fff
    style decision fill:#2196F3,color:#fff
    style step1 fill:#E8F5E9,stroke:#4CAF50

Dotted lines for async/error paths:

A -.->|"error path"| B    # dotted arrow
A -->|"happy path"| C      # solid arrow

Recommended diagram set for a design doc:

1. HLD — system architecture (always)
2. State lifecycle — if there are status transitions (always for stateful systems)
3. Main flow — SFN/workflow flowchart (always)
4. Sequence diagram — for multi-service API flows (when 3+ services involved)
5. Cancellation/error flow — if non-trivial error handling
6. Subsystem interaction — if there's a sidecar/decoupled module (e.g., comms)

Phase 4: Publish to Confluence

Always GET current version before PUT. Version mismatch = update rejected.

Confluence Storage Format — Key Macros

Lozenge colors: Green, Yellow, Blue, Red, Grey

Where to use each macro:

• Info panel → Overview, key design principles, important notes
• Note panel → Technical context (e.g., "The Scheduler service owns all delayed/recurring job dispatch")
• Warning panel → Critical constraints ("Do NOT cancel the timer")
• Expand → Long code blocks, pseudocode, detailed examples
• Status lozenges → Status tables (PENDENCY=Yellow, POST_PENDENCY=Blue, TERMINAL=Red), V1 vs V2 comparison (Red=old, Green=new), open questions (RESOLVED=Green)

Method 1: Jira MCP (preferred — works for both read and write)

# Read page + version
mcp__jira__jira_get 
  path="/wiki/rest/api/content/{pageId}" 
  queryParams={"expand": "version"}
  jq="{version: version.number}"

# Update page (ALWAYS increment version)
mcp__jira__jira_put 
  path="/wiki/rest/api/content/{pageId}" 
  body={
    "id": "{pageId}", "type": "page", "title": "Page Title",
    "space": {"key": "SPACE_KEY"},
    "body": {"storage": {"value": "<html>", "representation": "storage"}},
    "version": {"number": currentVersion + 1, "message": "What changed"}
  }

Method 2: Playwright browser (for large pages or when Jira MCP has payload limits)

// Read + modify + push in browser context (avoids payload size issues)
await page.evaluate(async () => {
  const resp = await fetch('/wiki/rest/api/content/{pageId}?expand=body.storage,version', {
    headers: { 'Accept': 'application/json' }
  });
  const data = await resp.json();
  let body = data.body.storage.value;
  
  // Modify body...
  body = body.replace('old text', 'new text');
  
  // Push
  await fetch('/wiki/rest/api/content/{pageId}', {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' },
    body: JSON.stringify({
      id: "{pageId}", type: "page", title: "Title", space: { key: "KEY" },
      body: { storage: { value: body, representation: "storage" } },
      version: { number: data.version.number + 1, message: "Update" }
    })
  });
});

Method 3: Restore from version history (when you accidentally break content)

// Fetch old version body, apply fixes, push as new version
const resp = await fetch('/wiki/rest/api/content/{pageId}?expand=body.storage&status=historical&version=12');
const data = await resp.json();
let body = data.body.storage.value;
// Fix and push as new version

Phase 5: Upload Diagrams as Attachments

Diagrams must be PNG attachments, not inline Mermaid macros.

1. Copy PNGs to Playwright-accessible directory (.playwright-mcp/)
2. Create hidden file input on the page
3. Trigger file chooser → use browser_file_upload
4. Reference in body: <ac:image ac:width="900"><ri:attachment ri:filename="diagram.png" /></ac:image>

// Upload pattern
page.evaluate(() => {
  const input = document.createElement('input');
  input.type = 'file';
  input.id = '__upload';
  document.body.appendChild(input);
  input.addEventListener('change', async () => {
    const form = new FormData();
    form.append('file', input.files[0], input.files[0].name);
    await fetch('/wiki/rest/api/content/{pageId}/child/attachment', {
      method: 'POST', // POST for new, PUT for update existing
      headers: { 'X-Atlassian-Token': 'nocheck' },
      body: form
    });
  });
});
// Then click input → browser_file_upload with file paths

To update an existing attachment: Use PUT instead of POST with the same filename.

Phase 6: Review Cycle

Spawn agents for different review perspectives:

Review checklist that catches 90% of issues:

• Every status in the transition table has a "from" and "to"
• Every API has request AND response defined
• Every config property has a default value
• Every SQS queue is in the provisioning list
• Every external call has error handling defined
• Feature flag / kill switch exists
• Rollback plan is documented
• Monitoring / alerting is specified
• Cross-team dependencies are listed with owners

Phase 7: Implementation Plan

Write as local markdown — NOT on Confluence (impl plans change too fast).

Structure:

# Steps (small, testable units)
Each step has:
  - Files to create/modify
  - Code snippets showing the pattern
  - Test gate: "done when X passes"

# Checkpoints (verification gates)
Group steps into checkpoints. Don't move past a checkpoint until its gate passes.

# Dependency graph
What blocks what. What can run in parallel.

# Placeholder strategy
Stub external services with TODO implementations.
Build and test all internal logic first.
Swap stubs for real impls when external services are ready.

Placeholder pattern for external services:

// PLACEHOLDER — returns mock data until real service is ready
public ArchiveResponse archiveDocuments(String id, ArchiveRequest request) {
    // TODO: Replace with real HTTP call when archive API is deployed
    log.warn("PLACEHOLDER: archiveDocuments called for id={}", id);
    return ArchiveResponse.builder()
        .url("https://placeholder.com/mock.zip")
        .build();
}

Quick Reference: Confluence Page Structure

1. Title + Status Lozenge (IN REVIEW / APPROVED / DRAFT)
2. Appendix table (JIRA, Dev Owner, Stakeholders, QA, PRD, Figma, Repos)
3. Table of Contents (TOC macro, maxLevel=3)
4. HLD diagram (system architecture)
5. Overview (info panel — 3 key bullets)
6. User Journey (numbered steps, plain language)
7. Core design sections (enums, timers, state machine, SFN)
8. Status transition table (with colored lozenges)
9. Integration sections (DB, APIs, config, external services)
10. Cancellation / error handling
11. Sequence diagrams for multi-service flows
12. Schema changes summary (additive = safe for V1)
13. Config seeding SQL (expand macro)
14. What's NOT changing (validated list)
15. Open questions (all RESOLVED with green lozenges)

Quick Reference: Mermaid CLI

# Install
npm install -g @mermaid-js/mermaid-cli

# Render single diagram
mmdc -i flow.mmd -o flow.png -w 1400 -b transparent --scale 2

# Common sizes
-w 1600  # HLD, sequence diagrams (wide)
-w 1400  # Flowcharts, state machines (standard)
-w 1000  # Small diagrams (compact)

Common Mistakes