On this page
In short#
Three planes never mix: first-party marketplace, first-party marketing, third-party market intelligence. First-party data flows through Bronze, Silver and Gold; estimates live in their own store.
Three data planes#
| Plane | Sources | Lands in | Checked by |
|---|---|---|---|
| First-party marketplace | Seller APIs, seller CSV/XLSX exports | Bronze, Silver, Gold | Reconciliation against outside ground truth |
| First-party marketing | Ad, web-analytics, search, email and CRM accounts | Bronze staging, Silver, Gold | Reconciliation, assertions per grain |
| Third-party market intel | Market-data feeds and files, social listening | Its own estimate store | Not reconciled by design; labelled |
Marketplace is the money plane. Marketing conversions are platform-attributed, never summed across ad platforms and never shown as marketplace revenue. Third-party data has no ground truth to reconcile against, so it carries a badge and stays out of first-party KPIs and the measured outcome of a decision. HR, finance and warehouse records arrive through the same mapping contract as marketing files and are first-party; a content-intelligence corpus is a client-approved first-party deliverable, not a fourth plane (Organization datasets and measures).
The Platform API is a second reader of the third-party plane, and the only one outside MSO Cloud: connected apps read the social trend feed and the older per-org trend rows through one scope, platform:social.read. Marketplace and marketing planes have no scope. The routes that serve the shared trend feed are described in Platform API and events.
The six pillars#
| Pillar | Plane | Covers |
|---|---|---|
| ecom | First-party marketplace | Marketplace and offline orders, inventory, cost of goods |
| marketing | First-party marketing | Ad spend, web analytics, search data from the organization's accounts |
| crm | First-party marketing | Leads and deals; abstains when no lead or deal feed is connected |
| audience | First-party deliverable | Corpus, mentions and sentiment behind content-intelligence decks |
| social | Third-party listening | Buzz and sentiment from a listening feed; a signal, never a KPI |
| market | Third-party estimate | Category, competitor and product estimates; never a measured outcome |
ecom has no owning plugin: it turns on with a live marketplace connection or any order history. Every other pillar is owned by one plugin and resolves to an empty result when that plugin is off (Organization types, Connectors and data planes).
The medallion warehouse#
| Layer | Holds | Guarantee |
|---|---|---|
| Bronze | Raw, append-only ingest; staging rows with template version | Same payload twice is a no-op; fixes replay without the vendor |
| Silver | Typed facts from per-stream promoters | Replaying Bronze reproduces the same Silver |
| Gold | Rollups dashboards and reports read | Brand in every key; refreshed nightly and on demand |
Orders, creators and inventory are stored with a content hash; every other stream lands in staging. Mechanics: Ingest pipeline.
Money and time#
Money is a signed 64-bit integer of dong, serialized as a safe integer and formatted through one helper; averages and rates round once, at display. Time is Vietnam time on every date path: day buckets in Asia/Ho_Chi_Minh, projected as text and filtered with local day edges, so the screen equals the download. Every metric surface owes a reconciliation assertion whose expected value traces to external ground truth, never to a second derivation in code; a figure at a vendor ceiling renders as "at least N" rather than inventing a denominator (Measurement and honest numbers).
The signal registry#
Under the pillars sits a versioned, organization-scoped catalog of named signals, each with a schema, a unit, a time grain and a provenance tier (first-party, third-party or derived). A feature store holds per-period values; a missing value is stored as absent, not zero. Every proposed decision reads from this registry. Next step: From signal to decision.
Where it stops#
Third-party estimates are periodic, not real time, and never reconciled. Lead and deal feeds are often thin, so crm metrics abstain rather than fill the gap. Finance variance and waterfall cards: Project status.
Decisions#
| Decision | Why | Enforced by |
|---|---|---|
| Third-party data has its own store and label; excluded from KPIs, measurement and reconciliation | An estimate summed with an order total looks exact and is neither | Plane-isolation and audience-isolation audits; chat asserts zero market data when off |
| Every money value is a signed 64-bit integer of dong, formatted by one helper | Float money drifts; a total one dong off its download is not trusted | Column types, one formatter in @yng/, exact-integer reconciliation |
| Each metric is defined once; dashboards, reports, exports, alerts and chat call it | Two implementations disagree the first time a filter, merge or time zone changes | Single-source audits; reconciliation after real promoters on a real database |
| Day edges, SQL buckets and chart labels anchor to Asia/Ho_Chi_Minh; no UTC on date paths | A UTC day edge pulls seven hours of the neighbouring day into a range | Audits refuse bare date casts and UTC day labels; browser check under a month filter |