Technical documentation
The wine trade, as a graph.
Behind every bottle is a web of relationships: who grew it, who shipped it, who pours it. We resolve that scattered web into one living graph and hold it in common, so the whole trade can finally see how it connects. Every node below is real and every count is live. Click in and follow the threads.
First principles
What is a graph, and why we are one.
In computer science, a graph is the data structure for relationships: a set of nodes connected by edges. Unlike a table or a tree, it has no rows and no hierarchy: any node can connect to any other. It is the structure behind social networks, GPS routing, and the web itself. Four ideas carry most of the weight:
- Vertex (node)
- A thing. A producer, a wine, an importer, a restaurant.
- Edge
- A relationship between two things. “imports”, “distributes”, “pours”.
- Weight
- A value on an edge. A price, a case quantity, a confidence score.
- Directed · cyclic
- Edges point a way (vine → table), and paths recur (a buyer reorders).
The wine trade is already a graph. It just was never written down as one.
Every producer, importer, distributor, shop, and restaurant is a vertex; every “imports”, “distributes”, and “pours” is an edge; price and quantity are the weights; the flow from vine to table is the direction. That network is real and it is everywhere, but it lives scattered across PDFs, portals, and license rolls, legible to no single party, because each one sees only its own edges.
A graph owned by one node isn’t infrastructure. It’s a silo. So we resolve the latent trade graph and hold it as a commons: neutral, provenance-tracked, shared on the publisher’s terms. The value was always in the edges (the relationships between parties) which no one participant can see alone. We don’t own the graph. We make it legible, and hold it in trust.
Interactive · entity-relationship diagram
Explore the model as a graph.
The whole canonical model, live. Click any entity to open its field-level view: primary keys, foreign keys, and the sensitivity tier of every field. Follow a foreign key to jump to the entity it links, or focus one entity to fan out its cluster and walk the graph node to node. Counts are live public-graph facts.
Click an entity to expand its fields — 🔑 primary key, ⛓ foreign key (click to follow the link). Pick a focus to explore one entity’s cluster, then walk the graph node to node. Drag to rearrange · scroll to zoom.
The complete model · spec v0.10.0
Every entity, colored by the wall.
This map renders straight from the published standard, so it can never drift from what we actually ship. Each entity is colored by its visibility tier: public (free, crawlable), gated (paid: license dossiers, ownership & buyer contacts), private (tenant-owned commerce). Public entities show live counts; walled tiers show the tier instead of the value.
Supply
Producers, wines, people, vineyards.
producer—Producer
sku—Wine (SKU)
vintage—Vintage
brand—Brand
vineyard—Vineyard
vine—Vine
cellar—Cellar
Trade
Export agents, importers, distributors.
export_agent—Export Agent
importer—Importer
distributor—Distributor
territorygated · paidTerritory
Demand
Shops & restaurants, where it sells.
retailer—Wine Shop
restaurant—Restaurant
People
The individuals behind every org & venue.
person—Person
Reference
Regions, grapes, places, terms.
region—Region
grape—Grape
place—Place
term—Term
Accolades
Critics, awards, publications.
award—Award
critic—Critic
publication—Publication
Prospect
Ownership groups + buyer contacts (the L2 moat).
restaurant_groupgated · paidRestaurant Group
Commerce
Pricing, inventory, accounts (tenant-owned).
priceprivate · tenantPrice
inventoryprivate · tenantInventory
accountprivate · tenantAccount
25 entity types · 28 relationship types · generated from web/lib/spec.ts. The standard is the single source of truth; this view, the JSON Schema, and the JSON-LD context all derive from it.
The wall
What's public, gated, and private.
The radial diagram above is the public graph: free and anonymous. Two tiers sit behind a wall and never appear there: sensitive license-holder detail and the ownership/contact prospect layer (paid), and tenant-owned commercial data (private). The classification is part of the open standard; every field declares its tier.
Public · the diagram above
Identities + relationships + public web presence. Producers, wines, regions, who imports/distributes what, a venue’s existence and location.
Gated · paid
License-holder dossiers (legal name, address, permit/license numbers, precise geo), plus the prospect layer: which group operates a venue and who buys its wine. Public-sourced, but paid-only in aggregate.
Private · tenant-authorized
Tenant-owned commerce: pricing (always; per-recipient), inventory, sales, and customer/CRM. Never public; shared only with the accounts the publisher authorizes.
The edges
Every relationship, defined.
| Edge | From → to | Live count | What it means |
|---|---|---|---|
| produces | producer → wine | 0 | The grower made this bottling. |
| represents | export agent → producer | 0 | An export agent (courtier) represents the domaine for export. NEW layer. |
| imports | importer → wine | 0 | The importer brings this wine into the country. |
| distributes | distributor → wine | 0 | A distributor carries it within a state / market. |
| listed_by | retailer / restaurant → wine | 0 | A venue lists it on a shelf or wine list. |
| supplies | importer / distributor → venue | 0 | A seller supplies a trade customer — tenant-ELECTED public (which wines; never price/qty). NEW. |
| in_region | wine / producer → region | 0 | Geographic origin in the appellation hierarchy. |
| awarded | wine / producer → award | 0 | A critic score or accolade. |
| person_of | person → producer | 0 | A winemaker / owner / vineyard manager: role + tenure on the edge. NEW. |
| farms | producer → vineyard | 0 | The producer works this vineyard (estate / leased / purchased fruit). NEW. |
| sourced_from | wine → vineyard | 0 | A bottling's fruit comes from this vineyard. NEW. |
| grows | vineyard → vine | 0 | A vineyard grows a block of vines (age, density, rootstock, training). NEW. |
| yields | vine → grape | 0 | A vine block yields a grape variety: the living-material → variety link. NEW. |
| vinified_in | wine / producer → cellar | 0 | Vinified/aged in a cellar, incl. contract, shared, or neighbor cellars. NEW. |
| farmed_as | wine / producer → term | 0 | A farming practice (organic, biodynamic, regenerative). NEW. |
| uses_technique | wine / producer → term | 0 | A winemaking technique (carbonic, skin-contact, amphora). NEW. |
| operated_by | venue → restaurant group | 0 | A venue is run by a hospitality group: sell-the-parent. GATED (prospect layer). |
| leads_beverage_for | contact → group / venue | 0 | The beverage decision-maker for a group / venue. GATED (prospect layer). |
A path through the graph
One bottle, vine to table.
The sample path is loading from the graph.
Build on the graph