# High Level Design Doc > Generate a professional High-Level Design (HLD) document as a formatted Word (.docx) file — design principles, key design decisions and trade-offs, module-level design, major user journeys, non-functional requirements, performance considerations, and risks. Use this whenever someone asks for an "HLD," "high-level design document," "design rationale doc," or wants to document *why* a system was designed the way it was (as distinct from the structural component view, which lives in the companion architecture-document skill). Part of an enterprise handover documentation suite (see also: project-overview-doc, architecture-document, operations-deployment-guide, support-runbook, api-documentation, database-design, release-maintenance-guide) but fully usable standalone. - Skill: `vedkathe/high-level-design-doc` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add vedkathe/high-level-design-doc` - Raw SKILL.md: https://api.skillmd.com/api/skills/vedkathe/high-level-design-doc/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: VedKathe (https://skillmd.com/u/vedkathe) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/vedkathe/high-level-design-doc --- # High-Level Design (HLD) Document Generator Produce a single `.docx` document capturing the *design reasoning* behind a system — principles followed, decisions made and why, how key user journeys play out across components, and the non-functional bar the design targets. The structural "what components exist" view belongs in the companion `architecture-document` skill; this document assumes that context and builds on it. ## Sections (in this order) Cover page, Version History, Document Approval, Revision Log, and TOC are automatic — your `sections` array starts at "1. Design Principles". | # | Section | Content | Diagram? | |---|---|---|---| | 1 | Design Principles | Bullet list of the principles the design follows (e.g., stateless services, event-driven communication, single source of truth per domain) | | | 2 | Key Design Decisions | Table: Decision, Rationale, Alternatives Considered | | | 3 | Module Design | For each major module: responsibility, key interactions, how it's tested | **Sequence Diagram** for the most complex interaction | | 4 | Major User Journeys | For each key journey (pick the 3-5 that matter most): numbered-step walkthrough of user action and system response | | | 5 | Exception Handling Strategy | Error-handling conventions, how errors surface to callers/users, retry policy | | | 6 | Non-Functional Requirements | Table: Category (Performance/Scalability/Availability/Security/Usability), Requirement | | | 7 | Performance Considerations | Known bottlenecks, load-testing results if available, optimization notes | | | 8 | Risks | Table: Risk, Likelihood, Impact, Mitigation | | | 9 | Appendix | Related design documents, ADR links | | ## 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 design decisions, rationale, or NFR targets you have no basis for — a plausible-sounding fabricated rationale is worse than an honest gap, since a new team might treat it as the real reason a choice was made. Use `toBeCompleted("...")` for sections you lack real input for, explaining what's needed, and still generate everything else. ## 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 # High-Level Design (HLD) *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 `High_Level_Design.md` instead of `High_Level_Design.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 — architecture decision records, past design discussions, or ask directly about key trade-offs made and NFR targets. 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 .docx` (or `libreoffice --headless ...`), then `pdftoppm -jpeg -r 100 .pdf page` and view the images. 5. Save to `/mnt/user-data/outputs/High_Level_Design.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 const B = require("./scripts/docx_builder.js"); const sections = [ B.h1("1. Design Principles"), ...B.bullets(["Stateless services for horizontal scaling", "Event-driven communication between modules"]), B.h1("2. Key Design Decisions"), B.table(["Decision", "Rationale", "Alternatives Considered"], [["Chose PostgreSQL over DynamoDB", "Need for relational integrity across orders/inventory", "DynamoDB, MongoDB"]], [3200, 3200, 2600]), B.h1("3. Module Design"), B.h2("3.1 Order Service"), B.para("Owns order lifecycle state and validation."), // Prefer B.diagramImage(path, {caption}) with a real mmdc render when // possible (see "Diagram Policy" above) — diagramPlaceholder() is the fallback: B.diagramPlaceholder({ name: "Order Placement Sequence Diagram", purpose: "Show the interaction between client, Order Service, Inventory Service, and the database during order placement.", recommendedContent: ["Client", "API Gateway", "Order Service", "Inventory Service", "Database"], }), B.h1("6. Non-Functional Requirements"), B.table(["Category", "Requirement"], [["Performance", "p95 latency < 200ms"]], [2400, 6800]), B.h1("8. Risks"), B.toBeCompleted("Risk register wasn't provided — ask for known risks and their mitigations, or check the project's risk log if one exists."), ]; await B.buildDocument("/mnt/user-data/outputs/High_Level_Design.docx", { docLabel: "High-Level Design", title: "High-Level Design (HLD)", 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 senior engineer new to the project should finish this document understanding not just what was built, but why it was built that way — able to make consistent decisions when extending the system later.