Component Overview
While the Container Diagram defines the macro infrastructure, this C4 Level 3 Component Diagram zooms into the Semantic Layer (Cube Core) and the Frontend Analytical Workspace (SaaS Web App + FINOS Perspective).
It specifies how user requests flow from authentication to sub-second multi-tenant data retrieval, and how non-IT power users perform stateful pivot slicing, tree drill-downs, non-destructive outlier filtering, and custom ratio calculations directly in the browser.
1. Component Architecture Diagram (C4 Level 3)
C4Component
title Component Diagram - Semantic Governance & In-Browser Pivot Workspace
Person(power_user, "Business Power User", "Non-IT manager slicing data & building ratios")
Container_Boundary(webapp_boundary, "SaaS Web App (Browser Runtime)") {
Component(perspective_viewer, "Perspective Viewer UI", "Web Component / WebGL", "Interactive tree-pivot grid, filter bar & WebGL charts")
Component(perspective_wasm, "Perspective Engine", "C++ / Rust WebAssembly", "In-memory columnar table, ExprTK ratios & view filters")
Component(api_client, "Data & Preset Client", "TypeScript / Fetch", "Fetches governed Arrow/JSON streams & saves view states")
}
Container_Boundary(cube_boundary, "Cube Core (Semantic Layer)") {
Component(auth_middleware, "Security Context & RLS", "JWT Middleware", "Extracts tenant_id & injects WHERE filters")
Component(data_models, "Cubes & Hierarchies", "YAML / JS Schema", "Defines metrics, joins & tree dimensions (SKU Tree)")
Component(query_orchestrator, "Query Engine & Cache", "Cube Store / SQL Gen", "Generates Doris SQL & caches frequent slices")
}
ContainerDb(app_db, "PostgreSQL (App DB)", "Relational DB", "Users, tenants, and saved Perspective JSON view configs")
ContainerDb(datamart_db, "Apache Doris (Datamart DB)", "MPP Analytical DB", "Pre-computed star schema & materialized views")
Rel(power_user, perspective_viewer, "Drags dimensions<br/>& writes ratios", "UI Interaction")
Rel(perspective_viewer, perspective_wasm, "Updates view config<br/>& expressions", "JS / Wasm API")
Rel(perspective_wasm, api_client, "Requests data slice", "Async Call")
Rel(api_client, app_db, "Saves/loads<br/>pivot presets", "REST / SQL")
Rel(api_client, auth_middleware, "Sends query<br/>with JWT", "HTTPS / REST")
Rel(auth_middleware, data_models, "Applies tenant<br/>isolation", "Security Context")
Rel(data_models, query_orchestrator, "Resolves measures<br/>& tree levels", "Internal")
Rel(query_orchestrator, datamart_db, "Executes<br/>pre-computed SQL", "MySQL Protocol")
UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1")

2. Implementation Specifications (Context for Engineers & AI)
When implementing or extending the analytical workspace, developers and AI agents must adhere to the following component responsibilities:
A. Multi-Tenant Isolation (Security Context & RLS)
- Every API request from the browser must carry a signed JWT containing
tenant_idandrole. - Cube Core intercepts the token via
checkAuthand enforces database/schema routing (mart_<tenant_id>) plus row-level filters (queryRewrite) before generating SQL for Apache Doris. The frontend never constructs raw SQL.
B. Hierarchical Tree Dimensions (Cubes & Hierarchies)
- Multi-level business dimensions—such as Food Manufacturing BOMs or FMCG SKU Trees (
Division > Category > Sub-Category > SKU)—are explicitly modeled as ordered dimension arrays in Cube Core. - When loaded into Perspective Viewer, placing these ordered levels into the
group_byslot automatically renders an expandable/collapsible tree grid with dynamic subtotals at every node.
C. Non-Destructive Outlier Filtering (Perspective Engine)
- Power users frequently encounter operational anomalies (e.g., test transactions, raw-material yield spikes, or pricing errors) during preview.
- Applying a filter in Perspective Viewer (e.g.,
["Yield_Loss_Pct", "<", 25]) executes strictly inside the browser’s WebAssembly memory. It removes outliers from the active pivot/chart aggregation immediately without mutating the underlying Apache Doris Datamart or requiring a backend round-trip.
D. User-Defined Calculated Members (ExprTK Computed Columns)
- Non-IT users define custom ratios (e.g.,
"Gross_Margin" = ("Revenue" - "COGS") / "Revenue") using Perspective’s built-in Computed Expressions engine (ExprTK). - Crucial Design Rule: For ratio metrics across hierarchical tree levels, engineers should expose base additive measures (
SUM(Revenue),SUM(COGS)) from Cube Core so Perspective recomputes the ratio accurately at every parent/child aggregation level rather than averaging pre-calculated percentages.
E. State Persistence (Data & Preset Client -> PostgreSQL)
- Calling
viewer.save()in Perspective serializes the entire analytical state—activegroup_bytree levels,split_bycolumns, outlierfilterarrays,expressions(calculated ratios), andpluginchoice (Datagrid vs. Bar/Line Chart)—into a lightweight JSON object. - This JSON payload is stored in PostgreSQL (
user_saved_viewstable) scoped bytenant_idanduser_id, allowing instant one-click restoration of custom reports.
