Architecture Document

Architecture Document Generator

Produce a single .docx document answering "what does this system look like and how is it put together" — components, technology choices, code organization, data flow, and integration points. This is the structural view; design rationale and decision trade-offs belong in the companion high-level-design skill, and API/database specifics belong in api-documentation / database-design.

Sections (in this order)

Cover page, Version History, Document Approval, Revision Log, and TOC are automatic — your sections array starts at "1. Solution Overview".

Diagram Policy

Applies to the .docx path only — Markdown embeds Mermaid source directly instead of rendering anything (see "Output Format" below).

Prefer a real Mermaid diagram — rendered via mmdc and embedded with B.diagramImage() — over diagramPlaceholder(), but only once you have concrete structure to draw (real names, not "TBD"). Read references/diagram-generation.md when you're actually about to render one — it has the full build order, the bundled config (assets/mermaid-config.json), the exact mmdc flags, and token-saving tips. Skip it entirely if this document ends up needing no diagrams.

Missing Information Policy

Never invent components, technologies, or integrations you have no basis for. Use toBeCompleted("...") for sections you lack real input for, explaining what's needed, and still generate the rest of the document. If a real codebase is available, inspecting it directly (folder layout, package manifests, config files) produces far better output than asking the user to recall it from memory — prefer that when possible.

Output Format

Ask the user which output format they want, unless they've already said so in this request (e.g., "as a docx", "in markdown," "just give me an .md file") — a quick single-choice question is enough, don't block on it otherwise:

• Word document (.docx) — the default assumption if the person hasn't specified and their context suggests a formal deliverable. Follow "Using the builder" below.

• Markdown (.md) — no script needed, write the file directly. Use these conventions so it stays structurally equivalent to the docx version:

  • Front matter: instead of a cover page, open with the title as an # heading, the project name as an italic subtitle line, then a metadata table instead of separate Version History / Approval / Revision Log tables:

    # Architecture Document
    *Acme Order Platform*
    
    | Field | Value |
    |---|---|
    | Version | 0.1 |
    | Author | Jane Doe |
    | Date | 2026-07-19 |
    | Status | Draft |
    | Approved By | Jane Doe (Tech Lead) |
    

  • Headings: #/##/###/#### matching the same section levels used in the table above — don't flatten everything to one level, that's what keeps the document skimmable and consistent with the docx version.

  • Tables: standard Markdown tables.

  • Diagrams — unlike the .docx path, don't render or embed an image here. Write the actual Mermaid source directly in a fenced code block; GitHub, GitLab, Obsidian, and most modern Markdown viewers render mermaid code blocks natively, so this is a real diagram, not a placeholder:

    ```mermaid
    flowchart TD
        A[Client] --> B[API Gateway]
        B --> C[Order Service]
        C --> D[(Database)]
    ```
    

    Only fall back to a text placeholder if you don't yet have concrete enough detail to draw something real (mirrors toBeCompleted above):

    > 📊 **DIAGRAM PLACEHOLDER — TO BE COMPLETED**
    > Not enough detail yet to draw the System Architecture Diagram — need
    > the actual component names and how they connect.
    

  • "To be completed" callout — same blockquote treatment:

    > ⚠️ **TO BE COMPLETED**
    > Explanation of what input is needed to fill this in.
    

  • Save as Architecture_Document.md instead of Architecture_Document.docx.

Workflow

Ask the output format first (see "Output Format" above). For Markdown, skip straight to writing the file using those conventions — the numbered steps below describe the .docx path.

1. Gather what's available — ideally a codebase to inspect directly, otherwise ask for tech stack, repo structure, and integration list.
2. Draft each section as data using the builder functions below.
3. Build with scripts/docx_builder.js.
4. Skip PDF conversion by default — docx_builder.js is already tested and hardened (table widths and text alignment are enforced at the library level), so routine generations don't need a re-render just to confirm it worked. Only convert to PDF and view it if the user explicitly asks for visual verification, or if something about this generation is unusual (e.g., a new kind of content the library hasn't handled before, or a reported rendering problem). When you do need it: soffice --headless --convert-to pdf <file>.docx (or libreoffice --headless ...), then pdftoppm -jpeg -r 100 <file>.pdf page and view the images.
5. Save to /mnt/user-data/outputs/Architecture_Document.docx (or .md if that's the chosen format) and present it.

Using the builder (for the .docx path)

This library requires the docx npm package. Before running any script, check it's available with node -e "require('docx')"; if that fails, install it with npm install docx in the working directory first — don't assume it's pre-installed, since that varies by environment.

// Before running this script: render the diagram with mmdc, e.g.
//   mmdc -i context.mmd -o context.png -t neutral -e png -w 1600 -H 900 \
//        -s 2 -b white -p puppeteer-config.json
// (see "Diagram Policy" above for the full mmdc workflow and required flags)

const B = require("./scripts/docx_builder.js");

const sections = [
  B.h1("1. Solution Overview"),
  B.para("The platform exposes a public API consumed by the mobile app and web frontend ..."),
  ...B.diagramImage("./context.png", { caption: "Figure 1: System context — external actors and boundaries." }),
  // Fallback if mmdc isn't available or the diagram isn't concrete enough yet:
  // B.diagramPlaceholder({ name: "Context Diagram", purpose: "...", recommendedContent: [...] }),

  B.h1("3. Technology Stack"),
  B.table(["Layer", "Technology", "Version", "Notes"],
    [["Backend", "Node.js", "20.x", "Fastify framework"]],
    [2000, 3400, 1400, 2200]),

  B.h1("7. Package Structure"),
  B.toBeCompleted("Package/namespace layout wasn't provided — inspect the codebase's src/ directory or ask for the module dependency map."),
];

await B.buildDocument("/mnt/user-data/outputs/Architecture_Document.docx", {
  docLabel: "Architecture Document",
  title: "Architecture Document",
  subtitle: "Acme Order Platform",
  versionHistory: [["0.1", "2026-07-19", "Jane Doe", "Initial draft"]],
  approvers: [["Jane Doe", "Tech Lead", "", ""]],
  revisionLog: [],
  sections,
});

Available functions: h1/h2/h3/h4, para, bullets, table(headers, rows, widths), pageBreak, toBeCompleted(explanation), diagramPlaceholder({name, purpose, recommendedContent, notes}), and buildDocument(path, options). Always use heading functions for titles so Word's Table of Contents and Navigation Pane work correctly.

Success Criteria

A developer joining the project should be able to read this document and understand the system's structure, technology choices, and how data and requests move through it — well enough to know where to look in the codebase for any given concern.