Skip to content

REQUIREMENTS.md

Latest commit

 

History

History
149 lines (105 loc) · 9.14 KB

REQUIREMENTS.md

File metadata and controls

149 lines (105 loc) · 9.14 KB

Product Requirements Document (MVP)

1. Overview

The goal is to build a lightweight, responsive web management console for CubeOne (Community Edition). CubeOne is a high-performance, in-memory OLAP engine. This Web UI will serve as the primary interface for users to model data, manage cubes, and perform analysis via standard REST APIs.

⚠️ Design Disclaimer

Target UX: We aim to provide a "Classic Explorer" style interface familiar to FP&A professionals.

Note on References: The images and descriptions below refer to industry-standard layouts (similar to TM1 Architect) strictly for functional workflow and layout reference.

Do NOT copy any specific color schemes, icons, or proprietary visual assets. We are building a modern, original UI using open-source component libraries (e.g., Element Plus, Ant Design).

2. Core Design Philosophy

Important Distinction: While our Backend API (FastAPI) is Resource-Oriented (flat lists of Dimensions, Cubes, etc.), the Web UI must be Object-Oriented and Hierarchical.

We are NOT building a simple flat 'API Admin Panel'—we already have the built-in FastAPI docs for that. We are building a contextual management tool.

Concept Backend API (Flat) Frontend UI (Hierarchical)
Structure /cubes, /views, /dimensions, /subsets are separate endpoints. An "Instance" node visually contains its related Cubes and Dimensions.
A "Cube" node visually contains its related Dimensions, Views, and Rules.
A "Dimension" node visually contains its related Subsets.
Context Global. You get a list of all dimensions. Contextual. You see dimensions belonging to a specific Cube.
Navigation Linear. Tree-based drill-down.

3. Key Features & Specifications

3.1 Connection Screen

  • Input: Server IP, Port, Instance Name (Optional: Username/Password for future Enterprise compatibility).
  • Action: "Connect" button that calls /cube/list and /dimension/list or /server/status to verify connection.

3.2 The Navigation Tree (Side Panel) 🌲

Reference Image: docs/images/ui_ref_tree_structure.png

The left sidebar is the heart of the application. It maps the server structure into a collapsible Tree View. The frontend must reorganize the flat API data into the following hierarchy:

  • 📍 Root Node: Instance Name (e.g., "PA_Training")
    • 📂 Cubes (Folder)
      • 🧊 [Cube Name] (e.g., "Sales_Plan") -> Key UI Logic Here!
        • 📂 Dimensions (Virtual Folder)
          • Lists the specific dimensions used by this cube (e.g., "Version", "Month").
        • 📂 Views (Virtual Folder)
          • Lists saved views for this cube.
        • 📜 Rules (File icon)
          • Click to open the Rule Editor for this cube.
    • 📂 Dimensions (Folder - Global List)
      • 📏 [Dimension Name] (e.g., "Product")
        • 📂 Subsets (Virtual Folder)
          • Lists subsets belonging to this dimension (e.g., "Default", "All Products").

Developer Note (Chaining Calls): You will need to chain API calls. For example, when expanding Dimensions folder under a Cube node, you may need to call GET /cube/{cube_name} to find out which dimensions belong to it, and then render them as children nodes. Same for other components folder, such as views, subsets, etc.

3.3 The Cube Viewer (Data Grid) 📊

Reference Image: docs/images/ui_ref_cube_viewer.png

When a user opens a Cube or a View, the main content area should render a high-density data grid (Pivot Table).

Layout Requirements:

  1. Toolbar (Top)
    • View Selector: Dropdown to switch between saved views.
    • Actions: "Recalculate" (Refresh data), "Zero Suppress" (Hide empty rows/cols).
  2. Dimension Layout (Pivot Area)
    • Titles (Filters): Dimensions placed at the top. User selects one element to filter the data.
    • Rows: Dimensions stacked vertically on the left. Support nested headers (e.g., Year -> Quarter).
    • Columns: Dimensions placed horizontally across the top.
  3. The Grid (Center)
    • Read/Write: Cells should display values. (MVP: Read-only is fine; Goal: Editable inputs).
    • Freeze Panes: Row and Column headers must remain visible when scrolling.

3.4 Rule Editor 📜

When the Rules node under a cube is clicked:

  1. Load: Call GET /cube/rule/view_raw to retrieve the existing rule script. (Show blank if empty).
  2. Edit: Provide a simple code editor (e.g., Monaco Editor or simple Textarea).
  3. Save: Call POST /cube/rule/edit_raw to save the changes.

4. UI References (Visual Guide)

These images are for layout structure reference only.

A. Navigation Hierarchy

Tree Structure Layout Shows how Cubes, Dimensions, and Subsets should be nested.

B. Data Grid Layout

Cube Viewer Layout Shows the "Pivot" layout with Titles, Rows, and Columns.

5. API Integration Strategy & Endpoint Mapping

Crucial Developer Note: The CubeOne Server provides atomic REST APIs. The Frontend is responsible for chaining these calls and transforming the data structures (e.g., constructing a Tree from parent-child edges).

Below is the mapping between UI Components and the actual Server Endpoints.

5.1 Component: Navigation Tree (Side Panel) 🌲

The frontend needs to build a multi-level tree. Since there is no single "Get Whole Tree" endpoint, you must fetch metadata level-by-level or construct it from flat definitions.

UI Node Level Data Needed Target Endpoint Integration Logic
1. Instance List of Cubes /cube/list Call to get all cube names to populate the first level folders.
2. Cube Children List of Dims in a Cube /cube/get Input: { "names": "Sales_Plan" }.
Response contains "dimensions": [...]. Use this list to render the "Dimensions" folder under a specific cube.
3. Global Dims List of All Dims /dimension/list Populate the global "Dimensions" folder at the bottom of the tree.
4. Subsets List of Subsets /dimension/subset/list Input: { "dimension": "Product" }. Lists all subsets for that dimension.

5.2 Component: Dimension Hierarchy Editor 📏

The dimension editor needs to show the parent-child structure (Ragged Hierarchy).

Feature Target Endpoint JSON Payload Key Frontend Logic
Load Hierarchy /dimension/get { "name": "Year" } Critical: The response returns "edges": [ ["All_Years", "FY23"], ... ].
The Frontend MUST implement an algorithm to convert these flat parent-child pairs into a nested Tree structure for the UI.
Update Hierarchy /dimension/set { "name": "Year", "edges": [...] } To move a node, update the edges array and send it back.

5.3 Component: Cube Viewer (Data Grid) 📊

The Grid is the most complex component. It requires defining exactly what is on Rows, Columns, and Titles.

Feature Target Endpoint Usage Note
Render Grid /view/grid This is the core query API.
You must construct a JSON body defining the view layout:
{ "cube_name": "...", "rows": [...], "columns": [...], "titles": [...] }.
The server returns the calculated cell values.
Save View /view/set Saves the current grid layout definition to the server.
List Views /view/list Lists saved views to populate the dropdown selector.

5.4 Component: Rule Editor 📜

Feature Target Endpoint Usage Note
Read Rules /cube/rule/view_raw Returns the raw TM1-style rule script string (e.g., ['Sales'] = N: ...).
Save Rules /cube/rule/edit_raw Accepts the full rule script string. Note: This overwrites the existing rules for the cube.

💡 Tip for Frontend Developers: Please refer to CubeOne_Function_Reference) for the exact JSON request/response schema for each endpoint mentioned above.