Use cases

Purpose

A use-case page explains one entry of the Use Case catalog as a design: what the scenario needs, which resources meet it, and why the design takes the shape it does. The entry gives the page its title, its scenario, its products, and the reference architectures it can build. The page never coins a use case of its own. The catalog is maintained by Azion. A writer who needs an entry, or finds one wrong, asks for it before writing the page. The request goes through the repository’s issue templates, or through the catalog’s owner inside Azion. The reader arrives with a situation, not a task: a storefront that slows down during a sale, a live event that has to reach one more region.

A use case is theory, not a procedure. It carries what a reader needs to understand and decide: the products the scenario requires, the architecture, how each part of the design works and the reason behind it, and the metrics that show it working. The values each configuration takes, every procedure, every command, and every check live in the guides the page links. Each guide section that applies part of the design names the use case and holds the values it takes there, so an implementer, often an agent, builds it from those guides without asking a question.

Use cases live in the Use Cases section, never inside one product, under the Solution area of their catalog entry. The area’s label is the Solution name. The guides a use case links live in the Guides section.

When to use

Recognize a use case by:

• A title that is a Use Case name from the catalog, verbatim: an imperative verb phrase naming a workload, with no product names.
• A reader who arrived with a business situation rather than a task.
• A requirements table mapping each business need to the product that meets it.
• An outcome that stays measurable after the setup works.
• A design explained well enough that its linked guides, which carry its values and checks, build it without a question.

It is still a use case when:

• Its design has four parts or fewer. More than four means the entry is too wide for one page.
• It links every procedure, value, and check instead of repeating it here.
• It ships without a demo, because none exists. Never describe a demo that does not run.

Write something else when:

• The page describes one Reference Architecture with no customer scenario around it. That is an architecture page.
• The setup is a single task with no scenario around it. That is a how-to guide.
• The catalog has no entry for it, and the goal needs no customer situation. That is a multi-product guide. An entry makes the page a use case, whatever the wording of the goal.
• The reader has no scenario, only the product. That is a tutorial.

Register

Descriptive: 20 words per sentence, active voice, present tense. A use case states what each part of the design does and why. The imperative belongs to the guides it links. Tone: precise, plain, businesslike, sober. Sentence structure holds the rules.

Structure

Required components

• Scenario: three to five sentences from the catalog entry’s Scenario. They name the actor, the workload and the situation it is in, what this page sets up, and the measurable result. Followed by one line stating what the use case does not cover, the entry’s own exclusion.
• Prerequisites: a ## Prerequisites section, each item a link. The first item is the Azion account, with an inline link to the sign-up page: An Azion account. If you do not have one, [create an account](https://console.azion.com/signup). The other items name what the reader must already have, such as an origin, a domain, or a repository. Tools, tokens, and the example values belong to the guides.
• Required products: the requirements table. One row per requirement, naming the technical need, the product that meets it, and the page that documents it. The Product column holds the Products of the catalog entry. A dependency the product documentation confirms and the entry omits goes in the table too, and the gap is reported to the catalog. The technical need names the platform resource the reader configures.
• Reference architecture: a ## Reference architecture section. It opens by naming which of the entry’s Reference Architectures the page builds, then holds a legend of one or two sentences, a mermaid diagram, a numbered ### Dataflow directly under it, and, after the list, what the design shows that no step says, a ### Platform Resources list naming each Platform Resource and Feature with its role in this design, and ### Other designs for this use case, one bullet per other Reference Architecture of the entry.
• How the design works: a ## How the design works section that opens with one sentence naming what it explains, then one ### per part of the design that is specific to this use case, four at most, each a noun phrase such as ### The catalog cache. Each explains what that part does and why: the reasoning, the rule logic, and a diagram when the logic branches. A value appears only inside the sentence that gives its reason. It holds no values table, no step, no check, and no link line to a procedure. A part met by a guide’s defaults gets no subsection: the requirements table links the guide that documents it.
• Measuring results: a ## Measuring results section naming the metrics that show the setup working, and where to read each one.
• Best practices: a ## Best practices section holding recommendations about the design and the reasoning behind each.
• Guides in this use case: a ## Guides in this use case closing, a DocCardGroup with one card per guide that holds this use case’s values or checks: the title, the link, and what the guide does for this use case as the card copy.

Optional components

• Demo: a ## Demo section linking a running example, a template, or a repository. Omit it when none exists; never describe a demo that does not run.

The sections keep this order. What governs the page is proportion, not length. The page’s weight belongs in the decisions an implementer cannot make alone:

• The architecture and the design section carry the page. Together they say which resources the design uses, how they work together, and why. If they do not, the page is describing a scenario rather than designing one.
• Scenario, prerequisites, demo, and the guide cards stay brief. Each orients and hands off. A scenario that runs past a couple of paragraphs is selling.
• Measurement and best practices sit between the two. Each carries real content, a signal to watch or a reason, and neither is a place to expand.

The bound that keeps a use case honest is the four-subsection cap on ## How the design works, not a length. A sentence that needs a table, a step, or a command has put a guide’s content on the wrong page: it moves to the guide section that applies it, and the reason stays here.

Template

Copy the template and replace each <placeholder>:

Rules

• Explain the design; leave the doing to the guides. Every choice carries its reason, and nothing says “depending on your setup”. The reader may be an agent, and an agent cannot resolve an ambiguity by asking.
• Keep values, steps, checks, and code off the page. No fenced block other than the diagram, no table of settings, no <Tabs>, no <DocSteps>, no verification, and no command. The values a part of the design takes go to the guide section that applies it, under a line that names the use case, and the expected results go to that guide’s confirm section. When no guide holds the procedure, extend a guide or write a new how-to guide first, then link it.
• Narrow the scenario to one buildable setup. State it as A <team> that <has this> configures <this setup> so that <this checkable outcome>. If the sentence needs an “and also”, the entry is too wide for one page. Write the first setup and report the width to the catalog. Do not coin a second use case.
• Start from the requirements table. Every row is a requirement you have confirmed against the product. A requirement you cannot confirm does not go in the table.
• Explain what is specific to this use case. The guides carry how. The reasons the scenario changes a setting stay on the page. The values and the procedure that applies them live in the guide, which names this use case.
• Cap the design section at four parts. A part met by a guide’s defaults never counts: its guide is linked from the requirements table. More than four parts that need a subsection of their own means the entry is too wide for one page. Narrow the setup to the Reference Architecture the page builds and report the width to the catalog. Never raise the cap, and never coin a second use case.
• Diagram in mermaid. The diagram is text so that an agent reading the markdown twin gets the design, not an image reference. The numbered dataflow still carries the meaning: the diagram never stands alone.
• Draw the request and the way back. In the reference architecture flowchart, solid arrows (-->) carry the request, and dotted arrows (-.->) carry the response. A flow that runs apart from any request, such as 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 of the reference architecture diagram 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. A diagram in ## How the design works follows the list under it instead.
• 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. What the design shows and no step says, such as which part sits in the failure flow, goes after the list.
• Give each role one shape. The client is a stadium ((["Visitor"])), anything on Azion, a Product or a Platform Resource, is a rectangle (["application"]), a data store is a cylinder ([("KV Store")]), and a system outside Azion is a subroutine ([["commerce platform"]]). Shape and line style carry every distinction, never color.
• Run every flowchart top to bottom (flowchart TD), a chain of steps included. A chain drawn left to right grows wider than the column and shrinks its labels to fit.
• Open every diagram with the shared init line, as the template shows. It lays the diagram out with ELK, gives the labels room, and shrinks a diagram wider than the column to fit it. When the client does not render at the top, add an elk object right after "layout": "elk", with ELK’s model-order options, so the declaration order decides the layers: "cycleBreakingStrategy": "MODEL_ORDER", or "preset": "modelOrder", "keepEntryNodeOnTop": true.
• Measure, do not verify. The one-time check that a setup is correct lives in the guides’ confirm sections. The page names the ongoing signals that show the design still works.
• Keep best practices as recommendations with reasons, and keep them theory. A recommendation without its reason is an instruction in the wrong section. A practice that needs a command or a code sample belongs in a guide.
• Close with every guide the page routes to. ## Guides in this use case lists each guide that holds this use case’s values or checks, once.
• Never make a commercial claim. No cost saving, no percentage, no competitor, no customer name, and no assertion that a configuration makes anyone compliant.
• Example figures are not limits. A figure that frames the scenario stays in the scenario paragraph and appears nowhere else.
• Take the title, the scenario, and the products from the catalog entry. A request that arrives as a bare scenario, such as e-commerce or live streaming, is matched to an entry first. An entry makes the page a use case, whatever the wording of the goal. When no entry covers it, a goal that needs no customer situation is a multi-product guide. A customer situation the catalog should carry is proposed as an entry first. A use case is never coined on the page.
• Never invent a product name, a field, or a value. Take product names from Documentation terminology, and fields and values from the product, not from a URL or a directory path.
• Report the permalink when the page ships, so the catalog entry’s Docs field can read Published.

Examples

This excerpt of the use case Build e-commerce storefronts builds its Origin-hosted commerce platform storefront reference architecture. It shows the requirements table and one part of the design section:

Each row of the requirements table names a requirement, the resource the reader configures, the Product that meets it, and the page that documents it. The design part explains what the rule does and why. Its name, criteria, and behaviors sit in the guide section that creates the rule, under a line that names this use case:

Application Accelerator is not among the catalog entry’s Products. The Rules Engine reference confirms that the Bypass Cache behavior requires it, so the row carries it and the gap goes back to the catalog.

Related