Review Intelligence Framework

Pipeline

• Incremental ingestion per source with checkpointing; a failed run never loses the prior watermark.
• Theming and sentiment run as replayable jobs over source_record, versioned by model, so an upgrade re-derives history instead of re-scraping.
• Insight patterns run on a schedule per tenant, writing stable insight identities so status and age persist across runs.
• Pre-aggregated rollups by entity × theme × period for dashboard latency; the feed always queries the base table.

Statistical discipline

• Minimum-n threshold per tenant, applied to every ranking, benchmark, map shade and insight.
• Control bands for anomaly detection derived from the entity's own history, not a global constant.
• Comparison periods matched for length and seasonality; a 90-day window compares to the prior 90 days, with the same-period-last-year available.
• Every model reports precision on a maintained labelled sample, visible in the product.

Honesty constraints

• No revenue or footfall claim without that data joined at the same entity and period grain.
• Sentiment origin (model vs rating_derived) is carried through to every chart that shows sentiment.
• Percentages below a stated sample size render as a count, not a percentage — 2 of 3 is not 67%.
• A source outage is shown on any chart whose period it overlaps, so a volume drop is not read as a demand drop.

Performance targets

• Dashboard pages under 2s at p95 for a tenant with 5M feedback rows.
• Feed search under 1s at p95 with facets applied.
• Insight recompute within the nightly window for the largest tenant.
• Ingestion backlog alarm when any source exceeds its sla_hours.

Shell & configuration

• One codebase, one component library; tenants differ only by configuration and theme tokens.
• Branding applied from the config bundle at boot — logo, wordmark, accent, report cover.
• Nav built from the enabled page set; disabled routes 404.
• Filter registry is config-driven, so adding a tenant dimension needs no UI code.

Filters & state

• Global filter bar, state in the URL, preserved across navigation.
• Standard set: date, comparison, source, entity scope, rating, sentiment, theme, category, issue type.
• Saved views per user; shared views per team.
• Match count visible on the filter bar at all times.

Evidence & disclosure

• Every insight, KPI and chart element links to the reviews behind it.
• Every figure displays sample size and denominator; every chart states its excluded sources.
• Data freshness shown in the page header, not in settings.
• Confidence and limitations render as first-class page content, never tooltips.

Craft

• Semantic colour (critical / warning / healthy) is distinct from the tenant accent, so branding never changes what a status means.
• Tables sortable on every column, with sticky headers and a column picker.
• Keyboard navigation and visible focus throughout; charts have accessible table equivalents.
• Exports carry the filter state, the data-as-of timestamp and the limitations text.

Tenant safety

• company_id enforced at the data layer — row-level security or schema-per-tenant — never by application filtering alone.
• Token scoped to one company; a user provisioned for several signs in separately per company.
• Sign-out clears all cached tenant state, including saved views and local storage.
• No cross-tenant model training. Shared universal taxonomy, isolated tenant data.
• Per-tenant residency and retention honoured in storage, backups and exports.
• Audit log for every export, reply posted, permission change and config edit.

Scaling to hundreds of sources

• Connector SDK with a fixed contract: authenticate, fetch incrementally, emit a raw record, declare capabilities. A new source is a plugin, not a release.
• Capability declaration is load-bearing — granularity decides which pages a source may feed, automatically.
• Rate limiting, retry and backoff handled by the framework, not per connector.
• Onboarding a tenant is a config bundle plus an entity master import, targeted at days rather than weeks.
• Taxonomy versioned per tenant, with re-theming replayed from raw records.
• Config validated on write; an invalid bundle fails at provisioning, never at a user's login.

Data owners

• Store or product master: system of record, refresh cadence, unique key, and whether closed entities are retained.
• Which sources have owned accounts and API access, and who holds the credentials.
• Historical depth available per source, and whether backfill is permitted.
• Whether sales, footfall, inventory, ticket and CRM data can be joined — at what grain, with what lag, under what agreement.
• PII policy: what may be stored, for how long, in which region, and who may see reviewer identity.
• Existing warehouse and whether this platform reads from it or ingests independently.

Analytics owners

• Metric definitions already in use, so the KPI dictionary reconciles rather than competes.
• Existing taxonomy, tagging or coding frames worth preserving.
• Acceptable minimum-n threshold and confidence floor for publishing an insight.
• Whether a labelled sample exists for model evaluation, and who maintains it.
• Seasonality calendar: festivals, sale periods, launch windows, fiscal boundaries.
• Which claims the organisation will not accept without statistical backing.

Business owners

• The decisions this product must support, named concretely — and who makes each one.
• Current reporting cadence, formats and audiences to be replaced or fed.
• Escalation paths and SLAs already in force, so routing rules mirror reality.
• Entity hierarchy as the business actually uses it, including clusters and formats that are not on any org chart.
• Competitor set worth tracking, by market.
• What a good quarter looks like in this product's terms — the definition of success.

UI / product owners

• Primary users per page and their working context — desk, shop floor, mobile.
• Brand assets and any existing design system or token set.
• Localisation scope: interface languages, review display languages, date and number formats.
• Accessibility standard to meet, and whether it is contractual.
• Role matrix: who sees which entities, which fields, and who may export.
• Whether replying to public reviews happens in this product or stays in an existing tool.

Engineering owners

• Tenancy isolation model: RLS, schema-per-tenant or separate databases — and why.
• Identity provider and SSO requirements per tenant.
• Hosting, residency and compliance obligations by market.
• Expected tenant count, entity count and record volume at 12 and 36 months.
• Build-versus-buy for sentiment and theming, and the cost envelope for inference.
• Operational ownership: who is paged when a connector breaks at 3am.