Architecture pages

Purpose

An architecture page shows one Reference Architecture from the Use Case catalog: how Products and Platform Resources combine into one design. The reader wants to understand the shape of the design before building it.

It applies the explanation base form, the same form as a concept page. The difference is the subject: a concept page explains one thing, an architecture page explains how many things fit together.

When to use

Write an architecture page when:

• A design needs more than one Product or Platform Resource, and the relationship between them is the point.
• The reader must see the order of a request or a dataflow to understand the design.
• A guide keeps redrawing the same system in prose.

Do not write an architecture page when:

• The subject is one product or one idea. Write a concept page.
• The reader wants to build the thing. Write the use-case page that builds it, or a multi-product guide, and link it from here.
• The catalog has no entry for the design. Propose it to the Use Case catalog first; the page comes after the entry.
• The design cannot be drawn. A design you cannot draw is one you do not yet understand well enough to publish.

Register

Descriptive: 25 words per sentence, active voice, passive only when the actor is unknown. Tone: explanatory, plain, systematic. Sentence structure holds the rules.

Structure

The title is the Reference Architecture name from the catalog, verbatim. That name is a noun phrase naming the system built, such as Server-rendered headless CMS website, never with a Reference Architecture suffix. The opening paragraph is the entry’s Summary: what problem the design solves, and for whom. It names the Use Case the design implements, linked to the use-case page where one is published.

Required sections, in order

• ## Architecture diagram: a legend of one or two sentences, then the diagram as a mermaid code fence, with ### Dataflow directly under it.
• ### Dataflow: a numbered walkthrough of what moves where, with six items at most. After the list, what the design shows and no step says, such as which part sits in the failure flow.
• ## Components: one entry per Component of the catalog entry, with its role. Products go by name, Platform Resources lowercase as instances, and features and integrations labeled as the catalog labels them.
• ## Implementation: only links. The use-case page goes here when it builds this design, followed by the guides and Marketplace templates that implement all or part of it. A use-case page that builds a sibling design is linked from the opening paragraph, as the Use Case the architecture implements, and not here.
• ## Related resources: the closing section, a DocItem list, each row with its reason.

Template

Rules

• Draw the diagram in mermaid. The diagram is text, so an agent fetching the markdown twin reads the design itself instead of an image reference. Do not use an image for an architecture diagram.
• The diagram never stands alone. The numbered dataflow carries the meaning, and it stays even when the diagram renders.
• Label every node and edge in words, and never rely on color alone to carry a distinction.
• Follow the diagram rules in Components: the shared init line, top to bottom, and one shape per role.
• Draw the request and the way back. Solid arrows (-->) carry the request, and dotted arrows (-.->) carry the response. A flow that runs apart from any request, such as a publish, a purge, or a log stream, takes thick arrows (==>). A response arrow starts where the response starts: Cache on a hit, the firewall on a block, the origin on a miss. It passes through a node only when that node acts on the response, such as Cache storing a copy. A response the application handles returns through the application, which delivers it. A response the firewall gives goes straight to the client, because the application never receives that request. A read gets its way back too: a dotted arrow from the data store to the node that read it, labeled with what it returns. The legend above the diagram names what each arrow style carries.
• Number every arrow by its dataflow step. Each arrow label starts with the number of the ### Dataflow item it belongs to, such as 2, 4. miss. Every item has at least one arrow, and every arrow has an item. The way back belongs to the step it answers, so it never adds a step.
• Put the dataflow right under the diagram. The legend goes above the diagram, and ### Dataflow follows the fence with nothing between them, so the arrows and the steps they number are on screen together. A sentence that retells a step adds nothing and is cut.
• Name every component and say why it is there. A list of product names is a parts list.
• Link the implementation, do not inline it. Steps belong in a how-to guide or a multi-product guide.
• Write only the sections you can confirm. A required section whose content you cannot confirm with the team that owns the product is left out until you can, never filled with a guess.
• Report the permalink when the page ships, so the catalog entry’s Docs field can read Published.

Examples

• Deploy Jamstack websites: the published page the catalog maps to Git-driven static website. It carries a diagram, a numbered dataflow, the components involved, and links out to the implementation.

This trimmed excerpt shows the opening, the diagram section, and the dataflow of the Git-driven static website page. The catalog records that Reference Architecture under the Use Case Build and run marketing websites. No use-case page is published yet, so the Use Case is named without a link:

Related