# GB5 BI Platform — Documentation Set

This folder documents the GB5 BI platform: the governed BI Catalog/BI View model (three dataset
sources — Warehouse, ApiService via any existing report, and AnalysisQuery), the `gb5-widget`
rendering layer (KPI card, chart, table, pivot table), the dashboard portlet integration, and the
Portlet config screen that lets an admin wire all of it together without raw API calls or SQL.

**Status as of 2026-08-07**: The backend engine (all three catalog kinds, `RunBIQuery`, `MBIVIEW`
saved views, generalized field-mapping), all four `gb5-widget` rendering adapters, the dashboard
portlet-type integration, and the Portlet config screen (catalog picker, BI View authoring, field
mapping review) are code-complete, committed, and live-verified against GB5DEMO with real HTTP
calls — see [Analytics_Catalog.md](Analytics_Catalog.md) for exactly what "live-verified" means
for each piece, and what is *not yet* verified. In short: the full data pipeline (catalog picker →
BI View author/pick → `RunBIQuery` → real results, across all three catalog kinds except
AnalysisQuery) is proven end-to-end with real data on GB5DEMO, including two real bugs found and
fixed live (a post-rename stale endpoint path, and missing cache invalidation on three new write
paths). What is **not** yet confirmed is the actual pixel-level rendering of the pivot table's
toolbar-mode split and layout-save action — blocked by a known, pre-existing local dev-server
memory limitation, not this feature's code (proven instead via a clean type-check and targeted
unit tests asserting the exact toolbar-filtering logic).

## Who should read what

| You are... | Start here |
|---|---|
| **End user** (someone who will view a BI widget on a dashboard) | [Analytics_Overview.md](Analytics_Overview.md), then the "For End Users" section of each capability in [Analytics_Catalog.md](Analytics_Catalog.md) |
| **Client Admin** (sets up a BI-backed portlet for a client) | [Analytics_Overview.md](Analytics_Overview.md), then [Analytics_AdminConfigGuide.md](Analytics_AdminConfigGuide.md) |
| **Implementation Team** (decides which catalogs/measures a client should see, or turns one of their existing reports into a catalog) | [Analytics_AdminConfigGuide.md](Analytics_AdminConfigGuide.md), then the "For ImpTeam" notes per capability in the Catalog |
| **BE/FE developer** (extends the engine — a new adapter, a new dataset kind, filter support) | [Analytics_DeveloperPlaybook.md](Analytics_DeveloperPlaybook.md) is the main one; use [Analytics_Reference.md](Analytics_Reference.md) as your lookup table while coding |
| **Sales / Marketing** (positioning this to a prospect or client) | Not this folder — see the separate BI Platform collateral piece; this documentation set is internal/technical and functional, not customer-facing copy. |

## Files in this set

1. **[Analytics_Overview.md](Analytics_Overview.md)** — what this platform is, why it exists, the
   vision behind it, plain-language framing for non-technical readers, and an honest current
   status / roadmap.
2. **[Analytics_Catalog.md](Analytics_Catalog.md)** — one entry per capability (catalog registry,
   KPI/Chart/Table/Pivot widgets, BI Views, generalized field-mapping, dashboard integration,
   config screen): what it does, who uses it, what's configurable, verification status.
3. **[Analytics_AdminConfigGuide.md](Analytics_AdminConfigGuide.md)** — the step-by-step
   walkthrough of the Portlet config screen: exactly what an admin clicks, in order, to stand up a
   new BI-backed widget of any kind, including pivot-table authoring and turning an existing
   report into a catalog.
4. **[Analytics_DeveloperPlaybook.md](Analytics_DeveloperPlaybook.md)** — the architecture, the
   decisions behind it, and how to extend it (new adapter, new dataset kind, filter support, the
   pivot-table approach actually taken and why).
5. **[Analytics_Reference.md](Analytics_Reference.md)** — glossary, endpoint/dot-code table, key
   DTOs, schema, and the live GB5DEMO test data used throughout this set.

## Keeping this up to date

This is a living document set. Every future phase of this engine (filter support, direct
`Menu → BI View` access, a report-to-catalog screen, snapshots, AI-generated insights,
sharing/permissions, alerting) should:
- Add its entry to [Analytics_Catalog.md](Analytics_Catalog.md).
- Update the "What's built vs. what's next" section in [Analytics_Overview.md](Analytics_Overview.md).
- Add any new endpoint/dot-code/table to the tables in [Analytics_Reference.md](Analytics_Reference.md).

Don't get ahead of reality here. If something is "code complete but not browser-verified," say
exactly that; don't round it up to "done."