Your Developers Are Writing Architecture Docs Nobody Reads. Try This Instead.

FlowSquad generates High-Level and Low-Level Design documents directly from your codebase and requirements — always up to date, never out of sync with the actual implementation.

Why Do Static Docs Become Stale Immediately?

The incentive structure of architecture documentation is fundamentally broken. Writing docs is a large, upfront, unrewarded investment. The person best qualified to write them — the architect or tech lead who built the system — has the least free time. And the reward for writing good docs comes to future team members, not to the person who wrote them.

The result is predictable: docs get written once, at the point of maximum motivation (usually post-project retrospective or onboarding a new hire), and then progressively diverge from reality as the codebase evolves. The divergence compounds:

• After 3 months: component names and module paths in the docs no longer match the codebase
• After 6 months: architectural decisions described in the docs have been superseded by newer decisions that were never documented
• After 12 months: the docs describe the system that was originally built, which may share only a passing resemblance to the system that currently runs in production

A study of 200 enterprise software teams found that 73% of developers report that architecture documentation is rarely or never accurate relative to the current implementation. Despite this, teams continue to invest in documentation sprints, ADR (Architecture Decision Record) processes, and Confluence hierarchies that are out of date before they're published.

How Does FlowSquad's Design Generation Work? (2-Step Flow)

FlowSquad's HLD and LLD generation follows a two-step flow that mirrors how a senior architect would actually document a system — first understanding the big picture, then drilling into component-level detail.

Step 1 — Codebase Analysis and Context Building

FlowSquad uses its VectorDB index to perform a structural analysis of the codebase:

• Entry point detection: identifies API routes, CLI entry points, message queue consumers, and event handlers that define the system's external interfaces
• Module dependency graph: maps the import/dependency relationships between modules to identify layers and components
• Data model extraction: identifies database models, schemas, and ORM definitions to understand the data layer
• External integration detection: identifies calls to external APIs, cloud services, and third-party libraries that the system depends on
• Technology stack identification: detects frameworks, databases, message brokers, and deployment indicators from configuration files and dependency manifests

Step 2 — Document Generation

Based on the structural analysis, FlowSquad generates the design document via the configured LLM with the analysis as context. The generation is grounded in the actual codebase — not invented architecture that may not reflect reality. For large codebases, the generation uses multiple LLM calls (one per major component or layer) to stay within context window limits while maintaining coherence across the document.

What Is the Difference Between HLD and LLD in FlowSquad?

HLD and LLD generation can be triggered independently. Teams typically generate the HLD first to establish the architectural context, then generate LLDs for specific components on-demand as they're being developed or reviewed.

How Do You Export Designs Directly to Confluence?

FlowSquad's Confluence integration provides a one-click export from the generated design document to a new or existing Confluence page. The export:

• Creates the page in the specified Confluence space and parent page
• Formats the document using Confluence's native storage format (not raw HTML) — preserving heading levels, code blocks, tables, and list formatting
• Adds metadata labels: flowsquad-generated, hld or lld, and the project name
• Includes a generation metadata section at the bottom: generated date, FlowSquad version, codebase commit hash, and a "regenerate" link back to FlowSquad
• For HLDs, optionally generates a mermaid diagram of the system architecture as a code block (rendered natively in Confluence)

What Does a Generated HLD Actually Look Like?

Below is an excerpt from a FlowSquad-generated HLD for a Node.js + PostgreSQL e-commerce API:

This excerpt represents approximately 15% of a typical full HLD. The complete document includes a tech stack summary table, external integration descriptions, security architecture notes, deployment topology, and known architectural constraints — all generated from the actual codebase in under 8 minutes.

Teams report that FlowSquad-generated HLDs are directly usable in architecture reviews, saving tech leads 3–5 days of documentation work before each review cycle. Engineering VPs who previously had no reliable way to understand the current state of the system use the weekly regenerated HLD as their system status report.

# FlowSquad design generation configuration
design:
  hld:
    enabled: true
    output_format: "markdown"         # or "confluence"
    include_architecture_diagram: true # generates mermaid diagram
    regenerate_trigger: "manual"       # or "on_major_change"
    sections:
      - "system_overview"
      - "major_components"
      - "data_flows"
      - "external_integrations"
      - "security_architecture"
      - "deployment_topology"
      - "known_constraints"
  lld:
    enabled: true
    output_format: "confluence"
    scope: "component"                # one LLD per component directory
    include_sequence_diagrams: true
    regenerate_trigger: "on_pr_merge"  # auto-regenerate on merge
    confluence:
      space_key: "ENG"
      parent_page_id: "12345678"
      label: "lld-auto-generated"