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_id and role.
  • Cube Core intercepts the token via checkAuth and 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_by slot 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—active group_by tree levels, split_by columns, outlier filter arrays, expressions (calculated ratios), and plugin choice (Datagrid vs. Bar/Line Chart)—into a lightweight JSON object.
  • This JSON payload is stored in PostgreSQL (user_saved_views table) scoped by tenant_id and user_id, allowing instant one-click restoration of custom reports.

Leave a Reply

Your email address will not be published. Required fields are marked *