# 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](/en/documentation/style-guide/content/concept/). 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](/en/documentation/style-guide/content/concept/). - The reader wants to build the thing. Write the [use-case page](/en/documentation/style-guide/content/use-cases/) that builds it, or a [multi-product guide](/en/documentation/style-guide/content/multi-product-guides/), 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](/en/documentation/style-guide/writing/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 ````mdx import FrameBox from '@aziontech/webkit/frame-box' import ItemList from '@aziontech/webkit/item-list' import DocItem from '@aziontech/webkit/doc-item' ## Architecture diagram ```mermaid %%{init: {"layout": "elk", "themeVariables": {"fontSize": "13px"}, "flowchart": {"nodeSpacing": 24, "rankSpacing": 36, "padding": 8, "wrappingWidth": 150, "useMaxWidth": true}, "sequence": {"width": 120, "actorMargin": 30, "useMaxWidth": true}}}%% flowchart TD ``` ### Dataflow 1. 2. 3. ## Components - ****: . - ****: . ## Implementation - []() - . - []() - . ## Related resources . ```` ## 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](/en/documentation/style-guide/components/#mermaid-diagrams)**: 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](/en/documentation/style-guide/content/how-to-guides/) or a [multi-product guide](/en/documentation/style-guide/content/multi-product-guides/). - **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](/en/documentation/use-cases/build-and-run-applications/build-and-run-marketing-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: ````mdx A static website whose pages and content live in a Git repository. The Azion GitHub App builds the site on every push and deploys the output to Object Storage. An application serves the output through Cache, and a previous build can be redeployed to roll back. This design implements the Use Case *Build and run marketing websites*. ## Architecture diagram Solid arrows carry the request, dotted arrows carry the response, and thick arrows carry the publish flow, which runs apart from any request. Each label starts with the number of the dataflow step it belongs to. ```mermaid %%{init: {"layout": "elk", "themeVariables": {"fontSize": "13px"}, "flowchart": {"nodeSpacing": 24, "rankSpacing": 36, "padding": 8, "wrappingWidth": 150, "useMaxWidth": true}, "sequence": {"width": 120, "actorMargin": 30, "useMaxWidth": true}}}%% flowchart TD Client(["Client"]) App["application"] Cache["Cache"] Repo[["Git repository"]] GH["Azion GitHub App"] Bucket[("Object Storage bucket")] Client -->|"3. HTTP request"| App App -->|"4. request"| Cache Cache -->|"5. miss"| Bucket Bucket -.->|"5. file, stored"| Cache Cache -.->|"4, 5. file"| App App -.->|"4, 5. response"| Client Repo ==>|"1. push"| GH GH ==>|"2. build output"| Bucket ``` ### Dataflow Content moves through the design in this order: 1. A push to the repository triggers the Azion GitHub App, which builds the site. 2. The GitHub App deploys the build output to the Object Storage bucket. 3. A client sends an HTTP or HTTPS request to the domain of the application that serves the bucket. 4. In the data center, Cache answers the request from its copy of the file when it holds one. 5. On a cache miss, the application reads the file from the bucket, and Cache stores it for the next request. The publish flow moves only on a push, and the two flows meet only at the bucket. ```` ## Related - [Concept pages](/en/documentation/style-guide/content/concept.md): The same base form, for one idea rather than a system. - [Multi-product guides](/en/documentation/style-guide/content/multi-product-guides.md): The page that builds what this one describes. - [Images](/en/documentation/style-guide/formatting/images.md): Alt text and asset paths. - [Choose a content type](/en/documentation/style-guide/content/choose-a-content-type.md): The full catalogue of page kinds.