# Architecture Document

> Generate a professional Architecture Document as a formatted Word (.docx) file — solution overview, system architecture, technology stack, repository/module structure, data flow, integrations, caching, and messaging design. Use this whenever someone asks for an "architecture document," "system design doc," "solution architecture," or wants to document how a system's components fit together (as distinct from business context or database/API detail, which have their own companion skills). Part of an enterprise handover documentation suite (see also: project-overview-doc, high-level-design, operations-deployment-guide, support-runbook, api-documentation, database-design, release-maintenance-guide) but fully usable standalone.

- Skill: `vedkathe/architecture-document` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add vedkathe/architecture-document`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vedkathe/architecture-document/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: VedKathe (https://skillmd.com/u/vedkathe)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vedkathe/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".

| # | Section | Content | Diagram? |
|---|---|---|---|
| 1 | Solution Overview | How the system addresses the business need, conceptually | **Context Diagram** — system boundary, external actors, upstream/downstream systems |
| 2 | Overall System Architecture | Narrative walkthrough of all major components | **System Architecture Diagram** |
| 3 | Technology Stack | Table: Layer, Technology, Version, Notes | |
| 4 | Repository Structure | Table: Repository, Purpose, Link, Primary Language | |
| 5 | Folder Structure | Top-level directory layout with one-line purpose per folder | |
| 6 | Module Overview | Table: Module, Purpose, Owner, Repository | |
| 7 | Package Structure | How code is organized into packages/namespaces and dependency direction | **Package Diagram** |
| 8 | High-Level Data Flow | Narrative: how data enters, moves through, and exits the system | **High-Level Data Flow Diagram** |
| 9 | External Integrations Overview | Table: System, Type, Direction, Purpose (high-level only — detailed contracts live in the API Documentation skill) | **Integration Diagram** |
| 10 | Caching Strategy | What's cached, where, invalidation approach | |
| 11 | Queue/Event Design | Topics/queues, producers, consumers, delivery guarantees | **Queue/Event Flow Diagram** |
| 12 | Security Architecture | High-level AuthN/AuthZ approach, data protection, compliance posture (operational secrets handling lives in Operations & Deployment Guide) | |
| 13 | Known Architectural Limitations | Bullet list: what the current architecture doesn't handle well, and why | |
| 14 | Appendix | ADR links, related documents | |

## 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:

    ```markdown
    # 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:

    ````markdown
    ```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):
    ```markdown
    > 📊 **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:

    ```markdown
    > ⚠️ **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.

```javascript
// 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.