Document type: service_architecture_pattern

Table of Contents

This page defines the service_architecture_pattern document type. It is one entry in the document types taxonomy. The taxonomy page holds the general contract every document follows: frontmatter, state, linking and tags. This page holds only what is specific to service_architecture_pattern. The rest of the page calls a page of this type a pattern page.

1. Scope

A service architecture pattern governs how the services of the platform work together across a process boundary: the identity a call carries, how a message travels, how work that spans services stays consistent, how a failure or a load peak is contained, and who owns data. Three kinds of pattern are out of scope, because they have other sources and other readers:

  • Code-level design patterns, such as the Gang of Four's or a C++ idiom, which live inside one component.
  • User interface patterns, which belong to the journeys and the screens.
  • Local conventions, such as the SQL, HTTP and shell entity patterns of the codegen. They have no outside source, so they are conventions, and their pages keep their own type.

2. Contract

Implements
loading, citation. A pattern page loads what is known about one established pattern, and a design cites it by name: "use Token Exchange". See Regulatory Functions.
Folder
doc/knowledge/service_architecture_patterns/, one page per pattern, as pattern_<slug>.org. The hub, Service architecture patterns, lives in the same folder and orders the pages.
Scope
the page owns one pattern: its mechanism, its failure handling, its pitfalls and its sources. A use of the pattern is not this page's subject. The architecture page that uses the pattern owns the choices that are its own: the role, the subjects, the limits, the moments it acts. The pattern page names each use in * In ORE Studio and links it. It does not restate it.
Name
the title is the pattern's name in its authoritative source, for example Token Exchange or Idempotent Receiver. A name ORE Studio used before the page existed is an alias under * Also known as, never the title.
Group
#+pattern_group: places the pattern in one group of the language: identity, communication, coordination, resilience, load, data or observability. The scaffold refuses a pattern with no group or an unknown one.
Sources
at least one authoritative source: the book, catalogue or standard that defines the pattern, with the section. A page with no source is a local convention, not a pattern, and it belongs in an architecture page.
Level
cross.
(no term)
Not stateful. A pattern page has no TODO and no * Status table.
How to create
compass add service_architecture_pattern --pattern-group <group>. --parent-dir is optional and defaults to doc/knowledge/service_architecture_patterns/. See How do I create a new doc? for the flags.
Required sections (in this order)
  • Blurb: two to four sentences before the first heading. It names the pattern, states its intent and says where ORE Studio uses it. A pattern page has no * Summary heading; the blurb is the summary.
  • * Also known as: the other names, each with its source, and any local name.
  • * Context: the situation in which the problem arises.
  • * Problem: one question.
  • * Forces: what pulls in opposite directions.
  • * Solution: the pattern, with a diagram embedded with a #+caption: line and a [[proj:...png]] image, followed by the .puml source link and the plantuml -tpng regenerate line. The interaction diagram is the minimum. Add the diagram that shows the pattern's point when the interaction does not: a state machine when the pattern has a lifecycle, a class or object diagram when its point is a structure such as a token's claims, an activity diagram when its point is an order of decisions, a second sequence when its point is a contrast with a pitfall, and a component diagram when it is a composite. Place each one in the section whose point it makes.
  • * Failure handling: a table with one row each for errors, timeouts, retries, idempotency and observability. A row that does not apply says so and gives the reason.
  • * Pitfalls: the known ways the pattern goes wrong, with the symptom and the cause, including the ones ORE Studio has met.
  • * Security: the trust boundaries, and what a leak or a forgery costs.
  • * Resulting context: the benefits and the liabilities.
  • * In ORE Studio: each use, with a link to the page that owns it.
  • * Related patterns: the other patterns of the language, each with how it relates.
  • * Sources: the authoritative references.
  • * See also: the hub, and any other internal page.

3. A pattern page and an architecture page

The two pages answer different questions, and a fact belongs to one of them.

Question Page
How does the mechanism work, and how does it fail? the pattern page
What do the sources call it, and where do they define it? the pattern page
Which role, subject, limit or lifetime does this use choose? the architecture page
When does this component act, and why? the architecture page

A rule that both pages state drifts, and a reader finds the stale copy first. So an architecture page links the pattern for the mechanism, and the pattern page links the architecture page for the use.

4. A composite pattern

Some problems need several patterns together, for example scheduled work that must act as a tenant. A composite is a pattern page of its own. Its * Solution names the patterns it combines and links them, and it states only what the combination adds: the order, the boundaries between them, and the failures that arise between them. It cites the sources of its parts, and it may cite a source of its own when one names the combination.

Emacs 29.3 (Org mode 9.6.15)