Skip to content

Home Dashboard & Analytics

Referenced Files in This Document - Home.tsx - StatCard.tsx - PipelineRuler.tsx - useSectionFetch.ts - usePush.ts - status.py - history.py - config.py - status.json - index.html - package.json

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document explains the home dashboard interface, focusing on statistics visualization and real-time updates. It covers: - StatCard for key metrics display - PipelineRuler for processing pipeline status - Real-time data via Server-Sent Events (SSE) - Dashboard layout with customizable widgets, date range filtering, and responsive grid - Data fetching hooks, caching strategies, and error handling - Adding new statistical widgets and configuring layouts - Backend integration for real-time analytics and system health monitoring

Project Structure

The dashboard is a React application under apps/dashboard. The home page composes reusable components and hooks to fetch and render metrics. Key files include: - Page entry: Home.tsx - Custom widgets: StatCard.tsx, PipelineRuler.tsx - Hooks: useSectionFetch.ts (fetching), usePush.ts (SSE) - Backend routes: status.py, history.py - Shared configuration: config.py - Cache file used by backend: status.json

graph TB
subgraph "Dashboard Frontend"
A["Home.tsx"]
B["StatCard.tsx"]
C["PipelineRuler.tsx"]
D["useSectionFetch.ts"]
E["usePush.ts"]
end
subgraph "Backend Service"
F["status.py"]
G["history.py"]
H["config.py"]
I["status.json"]
end
A --> B
A --> C
A --> D
A --> E
D --> F
D --> G
E --> F
F --> I
F --> H

Diagram sources - Home.tsx - StatCard.tsx - PipelineRuler.tsx - useSectionFetch.ts - usePush.ts - status.py - history.py - config.py - status.json

Section sources - Home.tsx - StatCard.tsx - PipelineRuler.tsx - useSectionFetch.ts - usePush.ts - status.py - history.py - config.py - status.json

Core Components

  • StatCard: Displays a single metric with title, value, optional trend or icon, and supports loading and error states. It is designed to be lightweight and theme-aware.
  • PipelineRuler: Visualizes the processing pipeline stages and their current status, highlighting active, completed, and failed steps.
  • Home page: Orchestrates widget rendering, applies date range filters, and manages SSE connections for live updates.

Key responsibilities: - StatCard focuses purely on presentation and minimal state. - PipelineRuler maps backend pipeline status into a visual timeline. - Home coordinates data fetching, SSE subscription, and UI composition.

Section sources - StatCard.tsx - PipelineRuler.tsx - Home.tsx

Architecture Overview

The dashboard follows a clear separation between UI components and data access: - UI layer: Home page composes StatCard and PipelineRuler. - Data layer: useSectionFetch handles REST calls; usePush subscribes to SSE events. - Backend: status and history endpoints serve metrics and logs; status.json persists runtime state.

sequenceDiagram
participant UI as "Home.tsx"
participant Hook as "useSectionFetch.ts"
participant SSE as "usePush.ts"
participant API as "status.py"
participant Hist as "history.py"
participant Store as "status.json"
UI->>Hook : "Fetch initial metrics"
Hook->>API : "GET /api/status"
API-->>Hook : "Metrics payload"
Hook-->>UI : "Render StatCards"
UI->>SSE : "Subscribe to SSE"
SSE->>API : "Connect /api/events"
API-->>SSE : "Stream events"
SSE-->>UI : "Update metrics in real time"
UI->>Hook : "Filter by date range"
Hook->>Hist : "GET /api/history?from=...&to=..."
Hist-->>Hook : "Filtered dataset"
Hook-->>UI : "Re-render charts/cards"
Note over API,Store : "Status persisted to status.json<br/>and read via config.py"

Diagram sources - Home.tsx - useSectionFetch.ts - usePush.ts - status.py - history.py - status.json - config.py

Detailed Component Analysis

StatCard

Purpose: - Present a single KPI with label, value, and optional contextual info (trend, unit). - Handle loading and error states gracefully.

Behavior: - Accepts props for title, value, and optional metadata. - Renders skeleton while loading and shows an error message when data fails. - Integrates with theme and responsive design.

Usage example path: - See how StatCard is composed within the home page to render multiple metrics.

Section sources - StatCard.tsx - Home.tsx

PipelineRuler

Purpose: - Show the processing pipeline stages and their statuses. - Highlight current stage and any failures.

Behavior: - Maps backend pipeline status to visual segments. - Supports hover tooltips and color-coded states. - Updates reactively when SSE events indicate pipeline changes.

Integration: - Consumes pipeline status from backend status endpoint. - Re-renders on SSE event updates.

Section sources - PipelineRuler.tsx - status.py - usePush.ts

Real-Time Updates via Server-Sent Events

Mechanism: - usePush establishes an SSE connection to the backend. - On each event, it dispatches updates to relevant components (e.g., refresh metrics or pipeline status). - Handles reconnection and errors automatically.

Flow: - Subscribe on component mount. - Update local state upon receiving events. - Unsubscribe on unmount to free resources.

Section sources - usePush.ts - status.py

Dashboard Layout, Widgets, and Date Range Filtering

Layout: - Responsive grid that adapts to screen size. - Configurable widget order and visibility.

Date range filtering: - Filters historical metrics using query parameters. - Triggers refetch and SSE re-sync when filters change.

Configuration: - Widget definitions can be extended by adding new entries to the layout configuration. - Grid spans are adjustable per widget.

Section sources - Home.tsx - history.py

Data Fetching Hooks and Caching Strategies

useSectionFetch: - Centralized hook for REST requests. - Provides loading, error, and retry logic. - Optional in-memory cache keyed by request parameters.

Caching strategy: - Short-lived cache for frequently accessed metrics. - Stale-while-revalidate pattern: show cached data immediately, then update after network response. - Cache invalidation on filter changes or SSE updates.

Error handling: - Network errors surface as user-friendly messages. - Retries with exponential backoff for transient failures.

Section sources - useSectionFetch.ts - status.py - history.py

Backend Integration for Metrics and Health

Endpoints: - Status endpoint serves current system metrics and pipeline state. - History endpoint provides filtered datasets based on date ranges.

Persistence: - status.json stores runtime status. - config.py reads shared configuration values.

Real-time: - SSE stream exposes incremental updates for live dashboards.

Section sources - status.py - history.py - status.json - config.py

Dependency Analysis

Frontend dependencies: - React-based components and hooks. - Vite build tooling and package management.

Backend dependencies: - FastAPI-style routing for status and history. - File-based persistence for status.

graph LR
Pkg["package.json"] --> Vite["Vite"]
Home["Home.tsx"] --> Stat["StatCard.tsx"]
Home --> Pipe["PipelineRuler.tsx"]
Home --> Fetch["useSectionFetch.ts"]
Home --> Push["usePush.ts"]
Fetch --> StatusAPI["status.py"]
Fetch --> HistoryAPI["history.py"]
Push --> StatusAPI
StatusAPI --> Cache["status.json"]
StatusAPI --> Conf["config.py"]

Diagram sources - package.json - Home.tsx - StatCard.tsx - PipelineRuler.tsx - useSectionFetch.ts - usePush.ts - status.py - history.py - status.json - config.py

Section sources - package.json - Home.tsx - status.py - history.py

Performance Considerations

  • Prefer memoization for expensive computations in StatCard and PipelineRuler.
  • Debounce date range changes before triggering refetches.
  • Use pagination or server-side aggregation for large datasets in history queries.
  • Keep SSE payloads small; send only deltas where possible.
  • Leverage browser caching headers for static assets.
  • Avoid unnecessary re-renders by splitting components and using stable keys.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues: - SSE not connecting: verify backend route availability and CORS settings. - Metrics not updating: check cache invalidation on filter changes and SSE event handlers. - Slow load times: inspect network waterfall and consider enabling compression. - Empty pipeline status: ensure status.json is writable and config paths are correct.

Diagnostic tips: - Inspect network tab for SSE frames and REST responses. - Validate date range parameters in history queries. - Confirm backend logs for errors during status writes.

Section sources - usePush.ts - useSectionFetch.ts - status.py - history.py - status.json - config.py

Conclusion

The home dashboard combines simple, focused components with robust data hooks and real-time updates. StatCard and PipelineRuler provide clear visualizations, while useSectionFetch and usePush manage data flow efficiently. With configurable layouts, date filtering, and thoughtful caching, the dashboard scales well for both small and large datasets.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

How to Add a New Statistical Widget

Steps: - Create a new component similar to StatCard if needed. - Extend the dashboard layout configuration to include the new widget. - Wire up data fetching in useSectionFetch or add a dedicated hook. - If real-time updates are required, handle the corresponding SSE event in usePush.

Example reference paths: - Widget definition and usage: Home.tsx - Base card component: StatCard.tsx - Data fetching hook: useSectionFetch.ts - SSE hook: usePush.ts

Section sources - Home.tsx - StatCard.tsx - useSectionFetch.ts - usePush.ts

Configuring Dashboard Layouts

  • Define widget entries with titles, keys, and grid spans.
  • Persist user preferences locally or via backend settings.
  • Ensure responsive behavior across breakpoints.

Reference paths: - Layout orchestration: Home.tsx - Build configuration: package.json - Entry HTML: index.html

Section sources - Home.tsx - package.json - index.html

Optimizing for Large Datasets

  • Implement server-side pagination and aggregation in history endpoint.
  • Use virtualization for long lists if applicable.
  • Reduce SSE frequency or batch updates.
  • Cache aggregated results with appropriate TTL.

Reference paths: - History endpoint: history.py - SSE hook: usePush.ts - Fetching hook: useSectionFetch.ts

Section sources - history.py - usePush.ts - useSectionFetch.ts