Meridian Coffee Roasters is a fictional specialty coffee company based in Portland, Oregon. Meridian sells single-origin coffees online, publishes brewing guides, and offers a subscription service. This walkthrough shows how Machine-First Architecture would be applied to Meridian's entire digital presence, pillar by pillar.
Every example below is implementation-ready. The structured data is valid JSON-LD. The HTML is semantic. The content follows the principles described in the framework. This is what Machine-First Architecture looks like when it ships.
Pillar 1
Identity
Can machines unambiguously identify who you are?
Before Meridian builds a single page, the team writes a canonical definition. This structured document defines what Meridian is in fields, not paragraphs. Every bio, directory listing, and schema block across every platform traces back to this source.
{
"name": "Meridian Coffee Roasters",
"type": "LocalBusiness",
"category": "Specialty Coffee Roaster",
"description": "Meridian Coffee Roasters is a specialty coffee company in Portland, Oregon that sources single-origin beans from 12 farms across Ethiopia, Colombia, and Guatemala, roasts in small batches, and sells direct to consumers online and through a subscription service.",
"founded": "2019",
"founders": ["Alex Chen", "Maria Torres"],
"location": {
"city": "Portland",
"state": "Oregon",
"country": "US"
},
"offerings": [
"Single-origin coffee beans",
"Coffee subscription service",
"Brewing equipment",
"Brewing guides and education"
],
"differentiators": [
"Direct relationships with 12 farms",
"Roast-to-ship within 48 hours",
"Full traceability from farm to cup"
]
}Meridian then maps every platform where the brand exists: website, Google Business Profile, Instagram, Yelp, Trade Coffee marketplace, and specialty coffee directories. Each platform gets a presence optimised for that platform's specific structured data format, all derived from the canonical definition above.
When Meridian adds a new origin or discontinues a product, the canonical definition is updated first, then propagated to every platform in the ecosystem map. The canonical definition is versioned. The propagation is systematic.
{
"@context": "https://schema.org",
"@type": "LocalBusiness",
"@id": "https://meridiancoffee.com/#organization",
"name": "Meridian Coffee Roasters",
"url": "https://meridiancoffee.com",
"logo": "https://meridiancoffee.com/logo.png",
"description": "Meridian Coffee Roasters is a specialty coffee company in Portland, Oregon that sources single-origin beans from 12 farms across Ethiopia, Colombia, and Guatemala.",
"foundingDate": "2019",
"founder": [
{ "@type": "Person", "name": "Alex Chen" },
{ "@type": "Person", "name": "Maria Torres" }
],
"address": {
"@type": "PostalAddress",
"addressLocality": "Portland",
"addressRegion": "OR",
"addressCountry": "US"
},
"sameAs": [
"https://www.instagram.com/meridiancoffee",
"https://www.yelp.com/biz/meridian-coffee-roasters-portland",
"https://www.tradecoffee.com/roasters/meridian"
]
}Pillar 2
Structure
Can machines extract your information?
Before Meridian designs its product page template, the team defines the data model. What discrete, extractable pieces of information must every product page contain? The design wraps around this model. The model does not conform to the design.
interface CoffeeProduct {
name: string;
sku: string;
price: { amount: number; currency: string };
weight: { value: number; unit: string };
availability: "InStock" | "OutOfStock" | "PreOrder";
roast_level: "Light" | "Medium" | "Dark";
origin: {
country: string;
region: string;
farm: string;
altitude: string;
process: string;
};
tasting_notes: string[];
roast_date: string;
best_before: string;
brewing_methods: string[];
review_aggregate: {
rating: number;
count: number;
};
related_products: string[]; // SKUs
subscription_available: boolean;
}Every field in this model is rendered as structured data on the page. The critical information appears in the first content block: name, price, availability, origin, and tasting notes. Not below a hero image. Not behind a tab.
The page is server-rendered. All product data is present in the initial HTML response. JavaScript enhances the visual presentation but the data exists without it.
{
"@context": "https://schema.org",
"@type": "Product",
"name": "Yirgacheffe Kochere Natural",
"sku": "MER-ETH-YKN-250",
"description": "Single-origin Ethiopian coffee from the Kochere washing station in Yirgacheffe, naturally processed at 1,900-2,100 meters altitude. Tasting notes: blueberry, jasmine, dark chocolate.",
"brand": { "@id": "https://meridiancoffee.com/#organization" },
"offers": {
"@type": "Offer",
"price": "22.00",
"priceCurrency": "USD",
"availability": "https://schema.org/InStock",
"seller": { "@id": "https://meridiancoffee.com/#organization" },
"shippingDetails": {
"@type": "OfferShippingDetails",
"deliveryTime": {
"@type": "ShippingDeliveryTime",
"handlingTime": { "minValue": 1, "maxValue": 2, "unitCode": "d" },
"transitTime": { "minValue": 2, "maxValue": 5, "unitCode": "d" }
}
}
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": 4.7,
"reviewCount": 89
},
"additionalProperty": [
{ "@type": "PropertyValue", "name": "Roast Level", "value": "Light" },
{ "@type": "PropertyValue", "name": "Origin", "value": "Yirgacheffe, Ethiopia" },
{ "@type": "PropertyValue", "name": "Process", "value": "Natural" },
{ "@type": "PropertyValue", "name": "Altitude", "value": "1,900-2,100m" },
{ "@type": "PropertyValue", "name": "Tasting Notes", "value": "Blueberry, Jasmine, Dark Chocolate" }
]
}The relationship architecture is explicit. Every product page links to its origin country page, its roast level category, related products, and the relevant brewing guide. Breadcrumbs declare the hierarchy: Home → Coffee → Ethiopia → Yirgacheffe Kochere Natural. A machine starting from the homepage can traverse the entire product catalogue through structured, declared relationships.
Pillar 3
Content
Can machines trust what you publish?
Meridian publishes brewing guides. Here is how a machine-first brewing guide differs from a conventional one. The conventional guide opens with a story about discovering pour-over coffee in a Tokyo café. The machine-first guide opens with the answer.
I still remember the first time I tasted a perfectly brewed
pour-over coffee. It was a rainy Tuesday in Shibuya, and the
barista moved with the precision of a watchmaker...
[400 words later]
The ideal water temperature for pour-over coffee is 200°F.The ideal water temperature for pour-over coffee is 200°F
(93°C), measured at the point of contact with the grounds.
Meridian Coffee Roasters tested 847 brews across three grind
sizes and found that temperatures between 195°F and 205°F
produced optimal extraction rates of 18-22%, while water
below 190°F consistently under-extracted regardless of grind
size or brew time.The machine-first version leads with a specific, verifiable claim. It names the entity (Meridian Coffee Roasters), states the methodology (847 brews, three grind sizes), provides measurable outcomes (18-22% extraction rate), and defines the boundary conditions (below 190°F). An AI system can cite this paragraph with confidence.
The human story about Tokyo can still appear further down the page. The structure is inverted, not the personality.
Every guide on Meridian's site carries structured authorship. Not a generic "Meridian team" byline, but a named author with credentials connected to the knowledge graph.
{
"@type": "Article",
"headline": "Pour-Over Coffee Brewing Guide: Water Temperature, Grind Size, and Extraction",
"datePublished": "2026-01-15",
"dateModified": "2026-03-10",
"author": {
"@type": "Person",
"name": "Maria Torres",
"jobTitle": "Co-founder and Head Roaster",
"affiliation": { "@id": "https://meridiancoffee.com/#organization" },
"sameAs": [
"https://www.instagram.com/mariatorrescoffee",
"https://sca.coffee/members/maria-torres"
],
"hasCredential": {
"@type": "EducationalOccupationalCredential",
"name": "SCA Certified Q Grader"
}
}
}Temporal signaling is explicit. The guide states that water temperature data was collected between October 2025 and January 2026 using Meridian's light-roast Ethiopian beans. When Meridian updates the guide with data from new origins, the update is declared: what changed, when, and why. Machines evaluate the freshness of individual claims, not just the page's last-modified date.
Each section of the guide is a self-contained knowledge unit. The water temperature section can be extracted and cited independently of the grind size section. Both work on their own.
Pillar 4
Interaction
Can machines act on your website autonomously?
A customer asks an AI agent: "Order me a bag of light-roast Ethiopian coffee, 250 grams, under $25." The agent navigates to Meridian's site. Here is what needs to happen for that transaction to complete without a human in the loop.
Discoverability of Actions
The product page declares what actions are available. The agent does not need to guess that a button labelled "Add to Cart" is clickable. The available actions, their required inputs, and their expected outcomes are declared as structured data.
{
"@type": "BuyAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": "https://meridiancoffee.com/api/cart/add",
"httpMethod": "POST",
"contentType": "application/json"
},
"object": {
"@type": "Product",
"sku": "MER-ETH-YKN-250",
"name": "Yirgacheffe Kochere Natural"
},
"expectsAcceptanceOf": {
"@type": "Offer",
"price": "22.00",
"priceCurrency": "USD",
"availability": "https://schema.org/InStock"
}
}Predictable Outcomes
When the agent adds the item to the cart, the response is structured. No toast notifications. No cart icon animations. Machine-readable state confirmation.
{
"status": "success",
"action": "item_added",
"cart": {
"items": [
{
"sku": "MER-ETH-YKN-250",
"name": "Yirgacheffe Kochere Natural",
"quantity": 1,
"price": 22.00,
"currency": "USD"
}
],
"subtotal": 22.00,
"shipping_estimate": 5.99,
"total": 27.99
},
"available_actions": [
{ "action": "checkout", "url": "/api/checkout" },
{ "action": "continue_shopping", "url": "/coffee" },
{ "action": "remove_item", "url": "/api/cart/remove", "params": { "sku": "MER-ETH-YKN-250" } }
]
}Error Recovery
The Yirgacheffe is out of stock. Instead of "Sorry, something went wrong," the agent receives a structured decision point.
{
"status": "error",
"code": "OUT_OF_STOCK",
"message": "Yirgacheffe Kochere Natural (250g) is currently out of stock.",
"item": { "sku": "MER-ETH-YKN-250" },
"restock_estimate": "2026-04-05",
"alternatives": [
{
"sku": "MER-ETH-SID-250",
"name": "Sidamo Bensa Washed",
"price": 21.00,
"currency": "USD",
"match_reason": "Same origin (Ethiopia), same roast level (Light), similar tasting profile",
"availability": "InStock"
},
{
"sku": "MER-ETH-YKN-250",
"name": "Yirgacheffe Kochere Natural",
"price": 22.00,
"currency": "USD",
"match_reason": "Exact product, larger size available",
"availability": "InStock",
"variant": "500g"
}
],
"available_actions": [
{ "action": "add_alternative", "url": "/api/cart/add" },
{ "action": "notify_restock", "url": "/api/notify", "params": { "sku": "MER-ETH-YKN-250" } }
]
}Trust and Verification
Before committing to the purchase, the agent verifies the transaction terms programmatically. No padlock icons. No "trusted seller" badges. Structured, verifiable data.
{
"@type": "Offer",
"seller": {
"@id": "https://meridiancoffee.com/#organization",
"name": "Meridian Coffee Roasters"
},
"priceValidUntil": "2026-04-30",
"hasMerchantReturnPolicy": {
"@type": "MerchantReturnPolicy",
"returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
"merchantReturnDays": 30,
"returnMethod": "https://schema.org/ReturnByMail",
"returnFees": "https://schema.org/FreeReturn"
},
"shippingDetails": {
"@type": "OfferShippingDetails",
"shippingRate": {
"@type": "MonetaryAmount",
"value": "5.99",
"currency": "USD"
},
"deliveryTime": {
"@type": "ShippingDeliveryTime",
"handlingTime": { "minValue": 1, "maxValue": 2, "unitCode": "d" },
"transitTime": { "minValue": 2, "maxValue": 5, "unitCode": "d" }
},
"shippingDestination": {
"@type": "DefinedRegion",
"addressCountry": "US"
}
},
"paymentAccepted": ["Credit Card", "Apple Pay", "Google Pay"]
}The agent now has everything it needs. The product matches the customer's criteria (light-roast, Ethiopian, 250g, under $25). The transaction terms are verified (30-day free returns, 3-7 day delivery, $27.99 total including shipping). The purchase completes without a human interpreting a single visual element.
What Changed
Meridian did not redesign its website. The visual experience for human visitors is unchanged. The coffee still looks beautiful. The brand story still reads well. The checkout flow still works the same way in a browser.
What changed is the layer underneath. Every piece of information has a structured representation. Every page answers the question "what data does this expose?" before it answers "what does this look like?" Every action has a machine-readable pathway. Every error is a structured decision point.
Defining the data models first did not slow the design process down. It made it faster. When Meridian's designers sat down to build the product page, they already knew exactly what information the page needed to contain. No debates about what to include. No lorem ipsums or placeholder text. The real content existed before the first wireframe, because the structure demanded it.
The humans who visit Meridian's site see the same experience they always did. The machines that visit can now understand, evaluate, and transact.
That is Machine-First Architecture.