Reference architecture

A reference architecture is a high-level design document that shows how Cloudflare products fit into a customer's existing infrastructure and maps their use cases to Cloudflare solutions. The tone is guiding and straightforward.

This page covers how to write one. For the published architectures themselves, refer to Reference architectures.

Write a reference architecture when you need to show, at the design level, how several Cloudflare products combine to fit a customer's environment and use cases. These documents are typically detailed. It is not:

• A concept. A concept explains one idea in depth, whereas a reference architecture shows how multiple products fit together in a real environment.
• A how-to. A reference architecture describes and designs rather than giving procedural steps.

For a single architecture that needs little written explanation, use a reference architecture diagram instead. For the full comparison, refer to Content types. For live examples, refer to Cloudflare Load Balancing Reference Architecture, Magic Transit Reference Architecture, and Evolving to a SASE architecture with Cloudflare.

• Title: a noun phrase naming the architecture or solution, such as "Cloudflare Load Balancing Reference Architecture".
• Description: name the solution and the products, say how they fit into existing infrastructure and for which use case, and name the intended audience, such as IT and security professionals.

Copy this skeleton and adapt it to your architecture:

---
title: <Noun phrase naming the architecture or solution>
description: How <products> fit <infrastructure> for <use case>, written for <the intended audience>.
pcx_content_type: reference-architecture
sidebar:
  order: 10
products:
  - product-a
---

Open with two or three paragraphs on the subject matter, then state who the document is for and what they will learn.

## <Architecture area>

Present the reference diagram with numbered callouts, and explain each element in prose so the meaning survives without the image.

## <Use case to solution>

Map the customer use case to the Cloudflare solution, and flag any caveats that affect how the architecture applies.

## Related links

Link the supporting how-tos, concepts, and product documentation with current routes.

• Diagrams are the signature component: a single reference diagram reflects the overall architecture, with captions and numbered callouts explaining each element, and supporting diagrams develop specific parts.
• Introduction and intended audience open the document in prose, with two or three paragraphs on the subject matter followed by who it is for and what they will learn.
• Notes and warnings flag caveats that affect how the architecture applies.
• PublicStats surfaces Cloudflare network statistics where they strengthen the case for the architecture.
• What does not fit: procedural steps, because a reference architecture designs rather than instructs. Link a how-to for implementation.

pcx_content_type: reference-architecture
products:
  - product-a
  - product-b

For more details, refer to pcx_content_type.

A reference architecture diagram is the lighter variant: a single diagram with numbered callouts and just enough text to explain it, for a solution that does not need a full written architecture. The tone is instructional and straightforward.

• When to use it: reach for it when one diagram carries the solution and needs little written explanation. Choose a full reference architecture when the design needs detailed discussion.
• Title: a noun phrase, as for a full reference architecture.
• Structure: a single reference diagram, numbered callouts that explain each element, a short description of what the diagram relates to, and related links to supporting content.
• Frontmatter: set pcx_content_type to reference-architecture-diagram.

• Text equivalents for every diagram. Explain each numbered callout in prose and give the diagram a text equivalent, because an agent cannot read the image and the meaning must survive without it.
• Literal product and use-case names. Name the exact Cloudflare products and the use case in text, not only inside the diagram, so the architecture is retrievable on its own.
• Load-bearing links. Link the supporting how-tos, concepts, and product docs with real, current routes, because the architecture points outward to implementation.