The insurer's demand is classified: outside brokers, regulated personal data, an email channel upstream, versioned events downstream, high risk. Two architects read the classification and disagree at once.
The first says: "It reads broker emails and the word 'smart' is in the request. It is an agent. Use the agentic case management pattern." The second says: "It accepts a submission, validates it and calls a provider. It is an API service. Use the integration pattern and keep models out."
Both choices would run. Each would install a different factory. Pick the agent pattern and the factory builds an agent harness, tool definitions and golden-case evaluations around a route whose job is to check twelve typed fields, and it lets an agent choose the next step in a workflow the business has already fixed: received, validated, assessed, recommended, awaiting underwriter, decided. Pick the plain integration pattern and the factory builds a clean contract, an adapter and contract tests, and it has no station at all for the step where a free-text email must become a structured submission. The first over-builds the parts that are already deterministic; the second has no place for the one part that is not.
The learner's question: which reference pattern fits an enterprise product, what does each pattern hold fixed and let vary, and how do you combine two when the product has two shapes?
A reference pattern is a shape of demand#
Plain English. A reference pattern is a proven starting design for one recurring kind of product. Choosing it decides most of the stations, checks and risks before anyone writes a line.
A reference pattern is a reusable, versioned solution for one kind of enterprise product: its fixed structure, its declared variation points, the stations that build it, the gates that accept it, and the risks it is known to carry. A tiny example: the integration-service pattern fixes a contract-first API, an adapter per external system and contract tests; a product varies only in which systems, which fields and which mappings. The consequence is speed with known checks: a team that picks the right pattern inherits years of decisions. The trade-off is the opening story: the wrong pattern imports the wrong stations, and the factory runs them faithfully.
From repetition to a pattern built one pattern from two small requests. This chapter is the catalog view: eight patterns an enterprise factory is likely to need, each a family of products, compared on the same five questions.
Before AI. Architecture teams have kept catalogs like this for decades: reference architectures for a web application, a message-driven service, a batch job, each with its approved stack, its review checklist and its known failure modes. Enterprise integration patterns named the messaging shapes. What a factory adds is that the catalog becomes executable: choosing a pattern selects a station graph and a set of gates, so the review checklist runs as code.
The five questions, asked of every pattern below:
- What stays fixed: the invariant skeleton every product of the kind shares.
- Variation points: what each product spec supplies.
- Typical stations and gates: what the factory runs to build and accept it.
- Risk profile: what tends to go wrong, and how much harm it causes.
- Wrong choice when: the shape of demand the pattern does not fit.
The stations named here come from the wizard lab's catalog (examples/labcore/b_wizard.py). Teaching reconstruction: every pattern id, version and station in that catalog is the lab's own, except document intake, which maps to Example C's real PAT-INTAKE-API 2.1.0 and its four real stations.
The eight patterns at a glance#
Six of the eight hold no model at all by default; in the lab's catalog only document intake and agentic case management add a model station. That is not a gap in the catalog; it is the site's recurring decision applied to enterprise shapes. A model belongs at a station only where the work is semantic interpretation of variable business content, and in most enterprise products that is one step, if any.
Fixed parts, variation points, stations and risk#
Here is the comparison. Read one row at a time; the prose after the table picks out what it shows.
| Pattern | What stays fixed | Variation points | Typical stations and gates (lab catalog) | Risk profile | Wrong choice when |
|---|---|---|---|---|---|
| CRUD portal | auth, role checks, audit, one data model, standard UI shell | entities, fields, roles, validation rules, screens | data model, API, UI, tests, migrations; contract check, migration dry run | access control mistakes; data loss in migrations | the work is a multi-step process or crosses systems |
| Event-driven workflow | event envelope, schema registry rules, idempotent handlers, retries | events, handlers, states, consumers | event schemas, handlers, workflow; event schema compatibility | duplicate or out-of-order events; old consumers broken by new versions | a person waits on a synchronous answer, or one service owns every step |
| Integration service | contract first, auth, idempotency keys, bounded retries, trace id | external systems, mappings, routes, timeouts | contract, adapter, contract tests; contract check | partner contract drift; retries that duplicate writes | the hard part is reading unstructured input or deciding |
| Document intake | intake skeleton, schema validation, personal-data masking, human review of drafts | document types, extraction fields, schemas, routing | Example C's four plus a retrieval index and golden-case evals; evals gate | confident wrong extraction; injected text in documents | inputs are already structured, so no reading is needed |
| Agentic case management | tool allowlist, run-time guardrails, trace per run, a person decides | tools, case model, evidence sources, golden cases | case model, tools, agent harness, tests; evals gate | wrong recommendation read as a decision; unbounded tool use | the workflow is fixed and the agent would only follow it |
| Analytical dashboard | read-only access, query layer, data freshness labels | metrics, filters, sources, audiences | queries, views, data tests | wrong numbers presented with confidence; stale data | users must change records or trigger actions |
| Batch / ETL | schedule, checkpoints, data-quality checks, reruns by date | sources, transforms, targets, schedule | pipeline, data-quality tests | silent partial loads; schema changes upstream | results are needed per request, in seconds |
| Modernization adapter | the legacy contract, recorded behavior, replay comparison | which behaviors to keep, which to change, cutover plan | record legacy behavior, adapter, replay tests | undocumented behavior consumers rely on | there is no legacy system, or its behavior may change freely |
Three things in the table are worth stating as rules.
First, the fixed column is where the platform team's investment goes, and it is mostly the same few things: identity, authorization, audit, idempotency, versioned contracts and traces. Those are the components the previous chapter versioned and measured with a blast radius (The factory learning loop). A family of eight patterns shares them; it does not copy them eight times.
Second, the risk column predicts the gates. A pattern whose characteristic failure is contract drift gets a contract gate; one whose failure is wrong output with high confidence gets evaluations on golden cases; one whose failure is undocumented legacy behavior gets replay tests. A gate that does not answer the pattern's characteristic risk is ceremony.
Third, the last column is the most useful one for choosing. Most wrong pattern choices are not made by picking a bad pattern but by picking a good pattern for a shape the product does not have, as both architects did.
The three that matter for the insurer#
Integration service#
The integration service is a contract between systems. Its fixed skeleton is the one Example C already implements: parse, authenticate, check the role, validate against a schema, keep an idempotency key for writes, write an audit record, emit versioned events, carry a trace id. Its variation points are the systems on the other side and the mappings to them. In the insurer's case those are the roof-data provider (stubbed in the example, with a 2,000 ms timeout and at most 3 attempts) and the downstream consumers of the six event types. Its characteristic risk is that a partner's contract moves, so its characteristic gate is a contract check, and Example C's ci_checks.py runs one that is proven to fail on a hand-edited contract.
Document intake#
Document intake turns something unstructured into a validated record. Its fixed parts are the same intake skeleton plus two that matter more here: personal data is masked in logs, and a draft produced by reading a document is reviewed before it becomes a record. Its variation points are the document types, the fields to extract and the target schema. Where a model reads the documents, the pattern adds evaluations against golden cases, and, for a retrieval-assisted variant, a station that builds the retrieval index. Its characteristic risks are a confident wrong extraction and text inside a document that tries to give instructions, which is why the series' case UW-005 (injected text in a retrieved passage) exists. RAG Engineering owns retrieval itself.
Agentic case management#
Agentic case management fits a case that stays open, needs evidence from several sources gathered with tools, and ends with a person's decision. Its fixed parts are a tool allowlist, run-time guardrails, a trace per run and the rule that the agent recommends and a person decides. It is the right shape for the underwriting review that Insurance factory: orchestration builds. It is the wrong shape for the intake service itself, because the intake workflow is fixed by the spec: the transitions from received to decided are listed in SPEC-INTAKE-001, and no agent chooses the next state.
Mapping the insurer's intake service#
A real product is often two patterns joined at a seam. The insurer's intake service is an integration service at its core and a document intake at its front door. The factory should build each half with its own pattern's stations and join them at a typed contract: the submission schema.
Diagram: The insurer's intake service · two patterns joined at a typed schema
Rows separate deterministic code from the places an agent sits. Columns follow a submission: the front door, the service core, and the decision. At the front door, the document-intake half reads a broker's email; an agent drafts a submission and a validation step or a person confirms it. The draft crosses the seam as a typed submission. In the core, the integration half is code: authentication, role check, schema validation, idempotency, audit, events, trace id. The underwriting agent calls the core as a principal with a limited role and may only record a recommendation. The decision route belongs to the underwriter alone. Example C builds the core; the email step is described, not run.
- Where an agent sits
- read broker email, draft a submission: Free text becomes a draft record; the only step here that needs a model.
- underwriting-agent calls assess: A principal with a limited role; checked by the same skeleton as every caller.
- Deterministic code
- validate the draft against the schema: The typed submission is the contract both halves are tested against.
- auth, role, schema, idempotency, audit, events: The eight-step skeleton runs for every request, from a broker or an agent.
- decision route underwriter only: A spec that opens the route to another role is refused at station 1.
- People
- broker or staff confirms the draft: A draft becomes a submission only after confirmation.
- underwriter decides: The model recommends; a person decides.
Read the diagram left to right. A broker's email arrives at the document-intake half, where reading free text is semantic work: this is the first place an agent sits, producing a draft submission that a person or a validation step confirms. The draft crosses the seam as a typed submission, and from there the integration half is deterministic code: authentication, role checks, schema validation, idempotency, audit, events. The second agent sits outside that core as a caller with a limited role: in Example C the underwriting-agent role may run the assessment and record a recommendation, never a decision. The decision route belongs to the underwriter role alone, and the pattern refuses any spec that opens it wider.
Two facts make the mapping honest. Teaching reconstruction: Example C builds the integration half; its service accepts a JSON submission and does not read emails, so the extraction step is described here, not run. And both agents are part of the product at run time. The factory that builds the product has its own station workers, a different thing: building an insurance agent and operating an underwriting agent are kept apart in Insurance factory: orchestration.
The wizard lab shows what each choice installs. The script below calls the lab's own plan function for the insurer's classified demand twice, once as document intake and once as an integration service without the document store and model provider. It was written for this page and run on a scratch copy of examples/labcore/.
import sys
sys.path.insert(0, "examples/labcore")
from b_wizard import plan # the wizard lab's planning rules (teaching reconstruction)
insurer = {"users": "partners", "data": "regulated", "risk": "high", "deploy": "container",
"integrations": ["rest-api", "event-stream", "document-store", "model-provider"]}
a = plan(dict(insurer, app="document-intake"))
b = plan(dict(insurer, app="integration-api", integrations=["rest-api", "event-stream"]))
for name, p in (("document intake", a), ("integration service", b)):
print(f"{name}: {p['pattern']['id']} {p['pattern']['version']}, "
f"{len(p['stations'])} stations, {len(p['gates'])} gates, {len(p['approvals'])} approvals")
print("only in document intake:", sorted(set(a["stations"] + a["gates"]) - set(b["stations"] + b["gates"])))
print("only in integration: ", sorted(set(b["stations"] + b["gates"]) - set(a["stations"] + a["gates"])))
print("run-time rule:", [x["who"] for x in a["approvals"] if x["when"] == "at run time"])
document intake: PAT-INTAKE-API 2.1.0, 7 stations, 9 gates, 7 approvals
integration service: PAT-INTEGRATION-API 2.0.0, 6 stations, 8 gates, 6 approvals
only in document intake: ['S-build-retrieval-index', 'S-run-golden-case-evals', 'S2-generate-contracts', 'S3-assemble-service', 'S4-write-manifest', 'evals on golden cases']
only in integration: ['S2-generate-contract', 'S3-generate-adapter', 'S4-run-contract-tests', 'S5-write-manifest']
run-time rule: ['a person decides every case; the model only recommends']
The difference is the agentic part, made visible. Choosing document intake adds a retrieval index, golden-case evaluations as both a station and a gate, and a run-time rule that a person decides every case. Choosing the integration service adds a dedicated contract-test station and none of the model machinery. Neither is wrong for its half. Each is wrong for the whole: the combined product needs the integration half's contract tests and the intake half's evaluations, and the seam between them is a schema both halves are tested against.
Choosing, and combining#
Diagram: Choosing a reference pattern · ask in order, stop at the first yes
The question lane runs top to bottom; each yes points to a pattern in the answer lane. Replacing or wrapping a legacy system: modernization adapter. Unstructured input to read: document intake for that part. A case that stays open while evidence is gathered and a person decides: agentic case management for that part. Read-only output: dashboard, or batch and ETL when results can wait for a schedule. Otherwise choose between a CRUD portal, an integration service and an event-driven workflow by who acts: people on records, systems on systems, or events carrying a process. Then repeat for each remaining part and join the parts at typed contracts.
- Ask in order
- replace or wrap a legacy system?: Recorded legacy behavior is the demand.
- unstructured input to read?: Emails, forms, files that must become records.
- a case stays open, a person decides?: Evidence gathered with tools over time, then a human decision.
- read-only output?: Views or scheduled loads; no records changed by users.
- Pattern for that part
- modernization adapter: Record, rebuild behind the same contract, replay and compare.
- document intake: A model drafts; validation and a person confirm.
- agentic case management: An agent recommends; a person decides.
- dashboard or batch / ETL: Correctness is numbers, freshness and complete loads.
- CRUD portal, integration service or event workflow: People on records, systems on systems, or events carrying a process.
The diagram asks five questions in order and stops at the first yes. Is the main job to replace or wrap a legacy system? Modernization adapter. Must something unstructured be read? Document intake, for that part. Does a case stay open while evidence is gathered and a person decides? Agentic case management, for that part. Is the product read-only? Dashboard, or batch if results can wait for a schedule. Otherwise the choice is between a CRUD portal (people editing records), an integration service (systems calling systems) and an event-driven workflow (a process carried by events). Then run the questions again for each remaining part of the product, and join the parts at typed contracts.
Combining has a cost worth naming. Each seam is a contract with two owners, a version and a contract test, and each pattern brings its own gates. Two patterns joined well cost less than one pattern bent to fit both shapes. Four patterns joined in one small product usually mean the demand was not classified, and should go back to Classify the enterprise demand.
Production pitfall. The most expensive pattern error is the agentic one in either direction. Choosing an agent pattern for a fixed workflow hands an agent decisions the business already made, and every one becomes a test case and a review. Choosing a pattern with no model station for a product that must read free text pushes the reading into hand-written parsing rules that break on the first unusual email.
In a coding agent. A coding agent staffing a station in any of these patterns gets the same deal: one work item, a checkout scoped to the files the pattern lets it touch, and the pattern's own gates deciding whether the work advances. The pattern decides where the agent works; the agent's account of its work decides nothing. Harness Engineering owns the controls around that run.
What this is not. This page compares product patterns. Organization-wide golden paths, templates and catalogs are Platform foundations; the split between a pattern file and a product's rules is Pattern versus configuration versus business logic; multi-agent coordination at run time is Agent Orchestration Engineering.
Try it#
Pick an app type from the eight patterns, then users, data class, integrations, risk tier and deployment target. The lab returns the pattern id, stations, gates, human approvals and a spec skeleton whose unknowns are questions for a person. It never deploys anything.
The table holds the lab's result for each app type with the lab's default other choices (internal staff, internal data, own database, low risk, container platform). It was written for this page from a scratch run of b_wizard.plan, because docs/LABS.md has no plain table for this lab yet. Every pattern id and version is the lab's own, except PAT-INTAKE-API.
| App type | Pattern | Stations | Gates | Model station |
|---|---|---|---|---|
| CRUD portal | PAT-CRUD-PORTAL 1.2.0 | 7 | 6 | no |
| Event-driven workflow | PAT-EVENT-WORKFLOW 1.0.0 | 7 | 6 | no |
| Integration / API service | PAT-INTEGRATION-API 2.0.0 | 6 | 6 | no |
| Document intake / RAG agent | PAT-INTAKE-API 2.1.0 (Example C) | 7 | 7 | yes |
| Agentic case management | PAT-CASE-AGENT 0.9.0 | 8 | 6 | yes |
| Analytical dashboard | PAT-DASHBOARD 1.1.0 | 6 | 5 | no |
| Batch / ETL | PAT-BATCH-ETL 1.3.0 | 5 | 5 | no |
| Modernization adapter | PAT-LEGACY-ADAPTER 1.0.0 | 6 | 5 | no |
The default choices include an own database, which adds a migrations station and a migration dry-run gate to every row. The case-agent pattern's version starts with 0, which under semantic versioning means initial development, where anything may change: a fair label for the least settled pattern in the catalog. No model runs in this lab or the examples behind it; where an example has an agent, it is a scripted stand-in, so these results show how the factory mechanics work, not how good any model is.
WatchAlgo in practice#
Observed in the repository (docs/EVIDENCE.md, sections 5 and 11): WatchAlgo's line is closest to a batch pipeline over a catalog of independent units: a work list rebuilt from disk, a file-locked queue, stateless workers, acceptance by code after each worker exits, checkpoint commits every 30 minutes. In this chapter's terms it is one pattern, a content-generation batch, with a model at two semantic stations (solution, tracer) and code everywhere else. It has no users to authorize, no partner contracts and no legacy system, so six of the eight patterns have nothing to map to. This site's reading: the parts that transfer are the batch and acceptance mechanics, which reappear in the batch/ETL pattern and in every pattern's acceptance gates; the cheap oracle does not transfer (The enterprise blueprint has the full table).
Enterprise translation#
In an organization the catalog is owned by the platform team and versioned like any pattern: each entry has an owner, an applicability statement, the gates it installs, its known risks and its wrong-choice conditions written down. Example C's pattern file already carries the first of those as data: "applies_to": "a service that accepts a document from an outside party, validates it, runs it through a workflow and records a human decision". A demand that does not match an entry's applicability statement goes to an architecture review instead of a forced fit.
Domain teams choose from the catalog at demand intake and record the choice, and the reason, in the spec. When a team needs a ninth shape, the honest path is a new pattern with a 0.y.z version, built from two or three real products, not a ninth switch on an existing one. What decides the timeline is rarely the pattern's stations; it is the seams with other teams' systems, which each pattern names as variation points and none can generate. Platform foundations covers the catalog itself.
Failure test#
The failure: the agentic case-management pattern is chosen for the intake service, and its agent is allowed to move the workflow, including into decided.
How the factory catches it: in Example C, at station 1. The intake pattern's constraint human_decision_roles: ["underwriter"] makes s1_validate_spec refuse any spec whose decision route admits another role. A scratch run on a copy with the agent added to record_decision printed route record_decision lets ['underwriter', 'underwriting-agent'] decide; pattern allows only ['underwriter'], and nothing was built. At run time the same rule holds in the generated service: the example's own run shows the agent's attempt to record a decision refused with 403 and nothing written. A case-agent pattern without that constraint would have built the opening; the constraint lives in the pattern so that no product can choose it away.
What to run or toggle: in the wizard, switch the app type between document intake and integration service with the insurer's choices and compare stations, gates and the run-time rule; in Example C, run run.py and read lines 4 and 7, the broker and the agent each refused at the decision route.
Where to go deeper#
- Platform foundations (next): golden paths, templates and the catalog these patterns live in.
- Pattern versus configuration versus business logic: inside one pattern, what is fixed, what is configuration, what is product logic.
- Insurance factory: contract intake: the integration half, built from
SPEC-INTAKE-001. - Insurance factory: orchestration: the underwriting review, where case management fits, and building versus operating an agent.
- Data and integration engineering: contracts, schema evolution and fakes behind the integration pattern.
- RAG Engineering: retrieval for the document-intake variant.
- Agent Orchestration Engineering: coordinating agents at run time.
Checklist for Monday#
- Write down, for each pattern in your catalog, its fixed parts, variation points, gates, characteristic risk and wrong-choice conditions.
- Choose a pattern per part of a product, not per product, and join the parts at typed contracts with contract tests.
- Put a model station only where something unstructured must be read or a case needs evidence gathered; keep fixed workflows in code.
- Put rules that must never vary, such as who may decide, into the pattern as constraints a spec cannot override.
- Give a new pattern a
0.y.zversion until two or three products have used it. - Send a demand that fits no pattern's applicability statement to architecture review, not to the nearest pattern.
Exercises#
- A broker portal where brokers edit their own contact details. Which pattern?
Answer 1CRUD portal
A CRUD portal: people edit records through a UI over an owned data model. Outside users raise the risk tier (sign-in, roles), not the pattern.
- Nightly, a file of yesterday's decisions goes to a reinsurer's system. Which pattern, and what is its characteristic gate?
Answer 2Batch / ETL; data-quality checks
Batch / ETL, with data-quality tests between steps and reruns by date; the partner's file format makes the target side behave like an integration contract, so add a contract check on the output file.
- Why does the intake service not need the agentic case-management pattern even though an agent calls it?
Answer 3The agent is a caller, not the workflow
The workflow is fixed in the spec and runs in code. The agent is a principal with a limited role (underwriting-agent: assess and recommend), checked by the same skeleton as every caller. Case management belongs to the underwriting review that sits around it.
Advanced perspective#
The seam between two patterns is a product of its ownVersion it, test it, give it an owner
When the intake half and the integration half are built from different patterns, the submission schema between them becomes the most important artifact in the product. It needs a version (Example C's spec already carries submission schemas 1 and 2, with roof_material added in v2 and a default of unknown for old records), a compatibility gate (the example's schema-compat gate checks that each version can read the one before), and an owner who approves changes on both sides.
The failure mode is a seam owned by nobody: the extraction half adds a field, the integration half ignores it, and the data silently stops flowing. Contract tests on both sides of the seam, run in both halves' pipelines, catch it. Data and integration engineering is the home of schema evolution.
Competing designs for the agentic partModel at a station, agent with tools, or a workflow engine with model steps
For the email-to-submission step there are three common designs. A model at one station: a single call extracts fields into the schema, validation rejects bad drafts, a person confirms; cheapest to test, because the output is one typed record. An agent with tools: the agent can look up a broker, fetch an attachment, ask for missing fields; more capable, much larger test surface, and it needs a tool allowlist and a trace per run. A durable workflow with model steps: the process is code in a workflow engine and each model call is one step. Product (Temporal, as documented on 2026-11-20): workflow code must be deterministic, and non-deterministic work, LLM calls included, belongs in Activities, which Temporal retries with timeouts.
This site's recommendation: start with a model at one station, move to an agent only when evidence shows the single call cannot reach the needed quality, and keep the decision steps in code either way.
How many patterns should a catalog hold?Each one is a product with an owner and a version line
Every pattern in the catalog costs an owner, a version line, a test suite, documentation and a deprecation policy. A catalog of eight maintained patterns is a serious platform investment; a catalog of twenty usually has twelve that nobody maintains. The useful measure is reuse: how many products each pattern has built in the last year, and how many class fixes it has shipped to them. A pattern that built one product is a project template that happens to live in the catalog.
The opposite failure is a catalog of one or two very general patterns with many switches. Each switch doubles the combinations to test, and the combinations nobody tested are where the escaped defects come from. The previous chapter's decision tree, one pattern or a family, applies here at catalog scale.
Pattern risk and demand risk are different axesA CRUD portal can be high risk
A pattern's risk profile says what tends to go wrong with that shape. A product's risk tier, set at demand intake, says how much harm a defect causes. They combine; neither replaces the other. A CRUD portal over regulated personal data for the public is a low-complexity shape with a high tier: simple stations, many approvals. An agentic case manager for an internal triage queue with reversible outcomes is a high-complexity shape with a medium tier. The wizard reflects this: the app type selects stations, while users, data class and risk tier add gates and approvals on top. Teams that infer the tier from the pattern under-protect the simple shapes, where most personal data actually lives.
In one breath#
A reference pattern is a versioned shape for one recurring kind of enterprise product: what stays fixed, what each product supplies, the stations and gates that build and accept it, its characteristic risk, and the demand it is wrong for. Eight shapes cover much of enterprise work, six of them with no model at all; the agentic part of a product belongs where something unstructured must be read or a case needs evidence gathered, never in a workflow the business has already fixed. The insurer's intake service is two patterns joined at a typed submission schema: document intake at the front door, where an agent drafts, and an integration service at the core, where code checks every caller, including an agent that may only recommend.
A catalog of patterns needs a home: a place where patterns, templates, versions and the products built from them are registered, owned and found. Platform foundations builds that home: golden paths, repository templates, artifact registries, environment configuration and the software catalog that makes a blast radius computable.