# Low Level Design (LLD) - Experiential UI ## 1. System Overview The **Experiential UI** platform is designed as a **Server-Driven UI** system. The core objective is to decouple the frontend presentation from the business logic by having an AI Agent dynamically generate the dashboard layout, content, and interactivity based on the user's role, persona, and operational data. ### 1.1 Goals - **Dynamic Generation**: Dashboard structure should not be hardcoded but generated on-the-fly. - **Role-Based Context**: The system must adapt to different user roles (e.g., Executive vs. Operator). - **Schema-Driven Rendering**: The frontend must act as a pure renderer of a backend-provided JSON schema. --- ## 2. Backend Architecture Design The backend will be divided into two primary components: the **API Server** for handling requests and the **Dynamic UI Agent** for generating the dashboard logic. ### 2.1 Server Layer (`backend/server/`) This layer will handle HTTP requests, authentication, and database interactions. - **`main.py`**: Will serve as the application entry point using **FastAPI**. - **Endpoint Requirements**: - `POST /dynamic-ui`: Must accept `user_id`, `user_role`, and an optional `user_prompt`. It will coordinate fetching data and invoking the agent. - `GET /api/users`: Utility endpoint to list available user personas for testing. - **`db.py`**: Will manage persistence using **SQLAlchemy (Async)** with **PostgreSQL**. - **Schema Requirements**: - `AppUser`: To store identity and role information. - `UserContext`: To store the unstructured `context` JSON (operational data) and `persona` descriptions required by the agent. - **`models.py`**: Will define the API Request/Response schemas (DTOs), ensuring strict typing by importing the `DashboardSpec` model from the agent package. ### 2.2 Dynamic UI Agent Package (`backend/package/dynamic_ui/`) This package will encapsulate the AI logic using **Pydantic AI** to ensure deterministic and structured output. #### Agent Workflow Design (`agent.py`) The agent must facilitate a **Chain of Thought** process to generate the dashboard. It should not directly "guess" the JSON but build it methodically using the following registered tools: 1. **`analyse_persona` (Tool)**: - **Goal**: Understand the user's explicit intent (prompt) and implicit needs (role). - **Output**: A structured analysis of user concerns and decision context. 2. **`analyse_data` (Tool)**: - **Goal**: Scan the provided `context` JSON to find anomalies, trends, or critical signals. - **Constraint**: Must strictly reference existing data fields; no data fabrication allowed. 3. **`plan_interactions` (Tool)**: - **Goal**: Define how widgets communicate. - **Mechanism**: Use a Pub/Sub model where widgets are assigned `channel_id`s. - **Output**: A map of controllers (broadcasters) and followers (listeners). 4. **`plan_layout` (Tool)**: - **Goal**: Determine the visual hierarchy. - **Output**: A grid definition (rows, columns, spans) optimized for the device and content density. 5. **`generate_dashboard_json` (Tool)**: - **Goal**: The final aggregation step. - **Output**: The strict `DashboardSpec` JSON that matches the frontend's expected schema. #### Schema Contract (`models.py`) A shared schema library is required to keep Backend generation and Frontend rendering in sync. - **`DashboardSpec`**: The root object defining the entire screen. - **`Section`**: Logical groupings of widgets with grid properties. - **`Widget`**: A polymorphic definition supporting: - `Card`: For KPI metrics and text. - `Chart`: For visual data representation (Bar, Line, etc.). - `Table`: For detailed record views. - `List`: For summarized items or logs. --- ## 3. Frontend Architecture Design (`frontend/`) The frontend will be a **React** application responsible for faithfully rendering the schema provided by the backend. It must utilize **TypeScript** to enforce the schema contract. ### 3.1 Rendering Engine Requirements - **`DashboardRenderer`**: - Must act as the root orchestrator. - Responsible for parsing the `DashboardSpec`. - Must instantiate `ThemeContext` and `SelectionContext` providers. - **Performance Integration**: Must support **Lazy Loading** of heavy widgets (intersection observer) and **Async Rendering** to prevent main-thread blocking. - **`Section` Component**: - Must implement a flexible **CSS Grid** layout system. - Needs to support variable column counts (`--dui-cols`) dynamically defined by the schema. - **Nesting Support**: Must support recursive rendering (`section` inside `section`) to allow complex layouts. - **Widget Factory**: - A mechanism to map `widget.type` (e.g., 'chart', 'card') to the specific React component implementation. - **Lifecycle Manager**: Wraps widgets to handle standardized `loading`, `error`, and `empty` states. ### 3.2 Component Specifications - **`Card`**: Needs to support multiple content slots: header, main content, and footer bullets. - **`Chart`**: - Should wrap a plotting library (e.g., **Plotly.js**). - Must handle `onClick` events to trigger state updates in `SelectionContext`. - **`Table`**: A responsive data grid implementation. - **`List`**: A list renderer supporting various styles (bullet, badge, numbered). ### 3.3 State Management Strategy - **`SelectionContext`**: - **Purpose**: To manage cross-widget interactivity without complex prop drilling. - **Logic**: - Store a map of `{ [channelName]: selectedValue }`. - Expose `broadcast(channel, value)` and `listen(channel)` capabilities. - **Reaction**: When a value changes, listening widgets must visually react (e.g., filter data or highlight bars). - **`ThemeContext`**: - To allow dynamic styling (colors, fonts) controlled by the schema or user preference. - **Design Tokens**: Standardize spacing, radius, and typography scales. - **Runtime Switching**: Allow switching themes without page reload (e.g., specific client branding). ### 3.4 Data Integration Layer - **`api.ts`**: - Typed functions to communicate with the Backend API. - Must validate response types against the shared `DashboardSpec` interface. - **Widget Data Adapter** (New): - While the Agent provides initial context, widgets may need to fetch detailed data independently. - Support `dataSource` property in Widget schema to trigger client-side data fetching (e.g., `fetchWidgetData(id)`). - **Streaming Support** (New): - Implementation of a WebSocket client for real-time updates (e.g., `Operational` dashboards). --- ## 4. End-to-End Data Flow The system implementation must support the following linear flow: 1. **Input Collection**: The frontend collects the User Role and an optional Text Prompt. 2. **Submission**: This data is posted to the `/dynamic-ui` endpoint. 3. **Context Retrieval**: The backend retrieves the relevant `context.json` specifically for that user/role. 4. **Agent Orchestration**: - The Agent is initialized with the User Persona and Data Context. - It iterates through the Tools: Analysis -> Interactivity -> Layout -> Assembly. 5. **Schema Generation**: The final `DashboardSpec` JSON is produced. 6. **Response Delivery**: The JSON is sent back to the frontend. 7. **Dynamic Rendering**: The Frontend parses the JSON and builds the Component Tree. 8. **Interactive Loop**: User interactions (clicks) are handled locally via `SelectionContext` to allow for immediate visual feedback (server-independent interactivity). --- ## 5. Embedding & Platform Integration (New) To support usage across different host applications (Enterprise Platform): 1. **Dashboard SDK**: - Export `DashboardRenderer` as a standalone NPM package (`@exp-ui/runtime`). - Decouple routing dependencies to allow embedding in arbitrary parent routes. 2. **Web Component Wrapper**: - Create a `` Custom Element. - Uses `react-to-webcomponent` to allow embedding in Angular/Vue applications. - **Interface**: - Props: `config` (JSON), `authToken`. - Events: `onDrilldown`, `onAction`. --- ## 6. Development Roadmap & Implementation Plan ### Phase 1: Shared Contract Definition - Define the `DashboardSpec` JSON schema using Pydantic (Backend) and TypeScript Interfaces (Frontend). - Establish the set of supported Widget types and their configuration properties. ### Phase 2: Backend Core - specificy the database schema for `UserContext`. - Implement the FastAPI boilerplate and `db.py` connection logic. - Implement the 'Mock' Agent to return static JSON for testing the API contract. ### Phase 3: Agent Intelligence - Implement the Pydantic AI Agent. - Develop the 5 specific tools (`analyse_persona`, etc.) with prompt engineering for each step. - Connect the Agent to the live `context` data. ### Phase 4: Frontend "Renderer" - Build the `DashboardRenderer` and `Section` layout engine. - Implement the basic `Card` and `List` widgets. - Implement the `Chart` widget using Plotly adapters. - Wire up the `SelectionContext` for interactivity. ### Phase 5: Drilldown & Navigation Framework (New) - **Requirement**: Allow deeper exploration of data found in the dashboard. - **Frontend**: - Implement a **Navigation Context** to handle drilldown actions. - **Widget Action Handler**: - Support `onDrilldown(target_id: string, params: object)` events on charts and list items. - Render a "Back" button or breadcrumb trail when navigating into a child view. - **Drilldown Views**: - Define a mechanism to fetch a *new* dashboard schema based on the selected item (e.g., clicking "East Region" requests a dashboard specifically for that region). - Support "Modal" vs "Full Page" transitions defined by the schema. - **Backend**: - **Agent Tooling**: - Enhance `plan_interactions` to support `drilldown` actions alongside `filter`. - Create a `resolve_drilldown` endpoint/agent mode that takes the context of the click (e.g., `region_id=east`) and generates a focused sub-dashboard. - **Schema Extension**: - Add `action: { type: 'navigate', target: 'dashboard', params: {...} }` to the Widget specification. ### Phase 6: Integration & Polish - Connect Frontend `api.ts` to the Backend endpoints. - Test with various Personas to ensure the Agent generates diverse and appropriate layouts. - Refine CSS and Theming for a polished look.