> ## Documentation Index > Fetch the complete documentation index at: https://docs.aviatrix.com/llms.txt > Use this file to discover all available pages before exploring further. # Architecture # Doc Type: Architecture > **Tier**: Concepts & Architectures | **Reader phase**: Understanding\ > **Back to tier overview**: [concepts-architectures/index.md](index.md) *** ## What it is An Architecture document describes a **generic, reusable design pattern** using Aviatrix. It is not tied to a specific solution or scenario — it captures a repeatable approach that can be applied across multiple contexts. Architecture documents sit at the conceptual design layer. They are more specific than a Component doc (they show how components combine) but less specific than a Validated Design (they do not document a particular implemented outcome). They do not contain configuration steps. The primary output is a **well-reasoned design pattern** an architect can evaluate, adapt, and apply to their context. *** ## Goal After reading an Architecture document, the reader can select and justify a design for their environment. They understand the design's components, trade-offs, and constraints, and they are ready to validate the design against their requirements or hand it off to an implementation team with enough context for them to proceed via the relevant Guides. *** ## Primary personas | Persona | How they use it | | - | - | | **Architect** | Primary audience. Uses this to design or validate a solution | | **Engineer** | Secondary audience. Understands the design intent before implementing via Guides | | **Technical Manager** | May skim to understand scope and risk before approving a project | *** ## When to create a new Architecture document Create a new Architecture document when: * There is a repeatable design pattern involving 2 or more Aviatrix components in a non-trivial relationship * The pattern can be described generically — without relying on a specific customer's topology, IP scheme, or environment constraints * The pattern is meaningfully different from existing Architecture documents One Architecture document per distinct pattern. Each significant variant (e.g., Hub-and-Spoke vs. Full-Mesh) should be its own document rather than a section within a larger one. Architecture documents exist independently of Solutions — a Solution may reference an Architecture pattern where one applies, but a Solution does not need to exist for an Architecture document to be created. *** ## Required sections 1. **Overview** — 3–5 sentences: what problem this architecture addresses, what it produces, and who it is for. Include a one-line "when to use this" statement. 2. **Architecture Diagram** — A visual representation of the design. Every Architecture document requires at least one diagram. The diagram type should match the content: topology diagrams for network architectures, hierarchical diagrams for policy or rule structures, flow diagrams for data-path or decision-path architectures. Use an embedded image (preferred) or an ASCII diagram. Label all relevant elements — Aviatrix components, cloud provider constructs, on-premises components, and the relationships or flows between them. 3. **Design Principles** — 3–5 named principles that guided the architecture (e.g., *Centralized Policy Enforcement*, *Least-Privilege Connectivity*). Each principle gets 2–3 sentences explaining why it was chosen and what it prevents or enables. 4. **Components** — List the Aviatrix components used in this architecture with links to their Component documents, and a one-sentence description of the role each plays in the design. 5. **Traffic Flows** — Describe the primary traffic patterns (e.g., east-west, north-south, management plane) and how each is handled by the architecture. Use a numbered list or `` for multi-hop flows. 6. **Variants and Trade-offs** — 2–4 named variants of this architecture (or trade-off decisions the architect must make), with a brief rationale for when each is appropriate. Use a table when comparing more than 2 options. 7. **Sizing and Scale Considerations** — Guidance on how the architecture scales: what changes at 10 VPCs vs. 100, what the bottlenecks are, and what thresholds warrant a different approach. 8. **Security Considerations** — Specific security properties of this design: what is protected, what is not, and what compensating controls are needed. 9. **Related Resources** — Links to: Validated Designs built on this architecture, and the Configuration Guides that implement it. *** ## Optional sections * **Architectural Prerequisites** — Only when the design has structural requirements that determine whether this architecture is applicable at all (e.g., a minimum number of cloud regions, specific network topology constraints). Do not document configuration, licensing, or cloud provider setup here — those belong in the Configuration Guides that implement this architecture. * **Limitations** — When the architecture has known constraints worth stating up front (cloud provider limits, performance ceilings, unsupported scenarios) * **Migration Path** — When teams are likely migrating from a legacy architecture and need a transition approach *** ## Tone & voice **Technical and reasoned.** The reader is an architect or senior engineer. Write with precision. Explain *why* design decisions were made, not just *what* they are. Use hedged language deliberately: "This approach is recommended when X; if Y is a constraint, consider the variant in Section 7." Avoid being prescriptive about things that legitimately depend on context. A good Architecture document teaches the architect how to think about the problem, not just what to copy. *** ## Length guidance **250–400 lines.** Shorter documents risk under-specifying the design. Longer documents often indicate scope creep — split by variant if needed. *** ## Frontmatter See [Frontmatter Standards](../frontmatter.md) for field definitions and formatting rules. Name the title after the architecture pattern, not a specific solution or product. Format: `[Pattern Name] Architecture`. Because one architecture may serve multiple solutions, avoid referencing a single solution in the title. Example: *Hub-and-Spoke Transit Architecture*. ```yaml theme={null} --- title: "[Pattern Name] Architecture" description: "A reference architecture for [problem domain] — covering design principles, traffic flows, variants, and scale considerations." --- ``` *** ## Mintlify components See [Style Guide](../style-guide.md) for component definitions and usage rules. Use `` for multi-hop traffic flows, `` for variant comparisons, and `` for component summary cards in the Components section. *** ## Linking * **Link in from**: Solution documents where this pattern applies (optional), Validated Designs that draw on this pattern, CNSF (for foundational architectures) * **Link out to**: Component documents referenced in the design, Configuration Guides for implementation, Validated Designs that prove the pattern *** ## Dos and don'ts | Do | Don't | | - | - | | Include a diagram — it is required; match the diagram type to the content (topology, hierarchy, flow) | Omit diagrams and rely on prose alone | | Explain trade-offs explicitly — name the alternative and when it applies | Present the design as the only way to solve the problem | | Reference Component docs for building-block detail | Re-explain what a Transit Gateway is — link to the Component doc | | Scope to the design decision layer | Include UI steps, CLI commands, or Terraform snippets | | Note scale thresholds and limitations | Leave readers to discover limits in production | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.