Compass - Nimbly Documentation

Dashboard Backend

18 min read

1. Overview

The API Statistics Dashboard Module consists of several sub-modules that handle different aspects of dashboards:

  1. Main Dashboard - General dashboard functionality
  2. Issue Dashboard - Issue-specific metrics and reports
  3. QC Dashboard - Quality control performance metrics
  4. Report Dashboard - Report-specific metrics and analytics

Each sub-module follows a clean architecture pattern with distinct layers:

  • Routes - Express router definitions for HTTP endpoints
  • Controllers - Request handling and response formatting
  • Use Cases - Business logic implementation
  • Models - Data structures and validation

The dashboard endpoints support both GET and POST methods, with POST methods (V1 versions) introduced to better handle complex filtering and query parameters.

2. Libraries and Dependencies

The following major libraries and dependencies are used in the API Statistics Dashboard Module:

  • Express - Web server framework
  • Mongoose/MongoDB - Database connectivity and models
  • @nimbly-technologies/nimbly-common - Common types, errors, and utilities
  • @nimbly-technologies/nimbly-backend-utils - Backend utilities (logging, pagination, etc.)
  • @nimbly-technologies/entity-node - Entity management
  • lodash - Utility functions for arrays and objects
  • moment - Date and time manipulation
  • papaparse - CSV parsing and generation
  • pdfmake - PDF document generation
  • pdfkit - PDF creation
  • ramda - Functional programming utilities
  • axios - HTTP client for API requests
  • date-fns - Modern date utility library
  • firebase-admin - Firebase administration for authentication

3. API Endpoints

3.1 Dashboard API Endpoints

EndpointMethodDescription
/dashboard/detailGETRetrieves dashboard details based on specified metrics
/dashboard/upsertMetricsPOSTCreates or updates metric customizations
/dashboard/metricsGETFetches available metrics customization
/dashboard/dashboard-filtersGETRetrieves available dashboard filters
/dashboard/dashboard-filtersPOSTCreates or updates dashboard filters
/dashboard/home-page-metricsGETRetrieves user overall metrics for homepage

3.2 Issue Dashboard API Endpoints

EndpointMethodDescription
/dashboard/issue/GET/POSTRetrieves issue dashboard data based on metrics (heatmap, issueList, issueChart, etc.)
/dashboard/issue/listGET/POSTFinds [issues](../Issue Tracker/IssueTrackerOverview.md) by entity ID
/dashboard/issue/detailGET/POSTRetrieves detailed issue metrics (VOC, IRR, health, overview)
/dashboard/issue/issueIDsGETRetrieves all available issue IDs
/dashboard/issue/download/viewGET/POSTGenerates issue dashboard list view for download
/dashboard/issue/downloadGET/POSTDownloads issue dashboard report
/dashboard/issue/weekly-completion-scorePOSTRetrieves weekly score metrics for [issues](../Issue Tracker/IssueTrackerOverview.md)

3.3 QC Dashboard API Endpoints

EndpointMethodDescription
/dashboard/qc/GET/POSTRetrieves QC performance results
/dashboard/qc/customGET/POSTRetrieves custom QC results
/dashboard/qc/downloadGET/POSTDownloads QC performance reports
/dashboard/qc/custom/downloadGET/POSTDownloads custom QC reports

3.4 Report Dashboard API Endpoints

EndpointMethodDescription
/dashboard/report/GET/POSTRetrieves report dashboard list based on metrics and viewBy parameters
/dashboard/report/detailGET/POSTGets detailed report metrics (RCR, overview, insight)
/dashboard/report/download/viewGET/POSTGenerates report dashboard list view for download
/dashboard/report/downloadGET/POSTDownloads report dashboard data

4. Function Flow Traces

4.1 Dashboard Main Flow

flowchart TD
    A[Dashboard Router] --> B[getDashboardDetail]
    A --> C[upsertDocument]
    A --> D[fetchMetricsCustomizaton]
    A --> E[dashboardFilters]
    A --> F[userOverallMetrics]
    
    B --> G[DashboardController.getDashboardDetail]
    C --> H[DashboardController.upsertDocument]
    D --> I[DashboardController.fetchMetricsCustomizaton]
    E --> J[DashboardController.dashboardFilters]
    F --> K[DashboardController.userOverallMetrics]
    
    G --> L[DashboardUsecase.getIssueReportRatio]
    H --> M[DashboardUsecase.upsertDocument]
    I --> N[DashboardUsecase.fetchMetricsCustomizaton]
    J --> O[DashboardUsecase.dashboardFilters]
    K --> P[DashboardUsecase.userOverallMetrics]

When a request hits the dashboard routes, it first goes through the appropriate middleware (usually an Express callback wrapper) before being processed by a controller method. The controller method parses the request parameters, validates them using models, and calls the appropriate use case method. The use case method implements the business logic, interacts with repositories or services, and returns the result to the controller, which formats it for the HTTP response.

Example Flow: GET /dashboard/detail

  1. Request hits the router which calls getDashboardDetail middleware
  2. DashboardController.getDashboardDetail method processes the request
  3. The metric parameter is extracted and a switch case determines which use case method to call
  4. For ‘issue-report-ratio’, it calls DashboardUsecase.getIssueReportRatio
  5. The use case processes the request and returns the result
  6. The controller returns the formatted result as the HTTP response

4.2 Issue Dashboard Flow

flowchart TD
    A[Dashboard Issue Router] --> B[getIssueDashboardList]
    A --> C[getIssueDashboardDetail]
    A --> D[getIssueIDs]
    A --> E[getDownloadIssueDashboardListView]
    A --> F[findIssuesByEntityID]
    A --> G[getDownloadIssueDashboard]
    A --> H[weeklyScoreMetrics]
    
    B --> I[DashboardIssueController.getIssueDashboardList]
    C --> J[DashboardIssueController.getIssueDashboardDetail]
    D --> K[DashboardIssueController.getIssueIDs]
    E --> L[DashboardIssueController.getDownloadIssueDashboardListView]
    F --> M[DashboardIssueController.findIssuesByEntityID]
    G --> N[DashboardIssueController.getDownloadIssueDashboard]
    H --> O[DashboardIssueController.weeklyScoreMetrics]
    
    I --> I1[DashboardIssueUsecase.getIssueHeatmap]
    I --> I2[DashboardIssueUsecase.getIssuesList]
    I --> I3[DashboardIssueUsecase.getIssuesInsightList]
    I --> I4[DashboardIssueUsecase.getIssueTrendsChartDetail]
    I --> I5[DashboardIssueUsecase.getDrillByIssueFlag]
    I --> I6[DashboardIssueUsecase.getDrillByIssue]
    I --> I7[DashboardIssueUsecase.issueReoccurredDrill]
    
    J --> J1[DashboardIssueUsecase.getIssueVOC]
    J --> J2[DashboardIssueUsecase.getIssueDetails]
    J --> J3[DashboardIssueUsecase.getScoreMetrics]
    J --> J4[DashboardIssueUsecase.issueOverviewDetails]
    J --> J5[DashboardIssueUsecase.getCompleteIssueInsightDetail]
    
    K --> K1[DashboardIssueUsecase.getIssueIDs]
    L --> L1[DashboardIssueUsecase.downloadIssueReportListView]
    M --> M1[DashboardIssueUsecase.getIssuesByEntityID]
    N --> N1[DashboardIssueUsecase.downloadIssueReport]
    O --> O1[DashboardIssueUsecase.weeklyScoreMetrics]

The Issue Dashboard has complex routing that depends on query parameters like ‘metric’ and ‘viewBy’. The controller methods have extensive switch-case logic to determine which use case method to call.

Example Flow: GET /dashboard/issue/?metric=heatmap&viewBy=issueRedFlag

  1. Request hits the router which calls getIssueDashboardList middleware
  2. DashboardIssueController.getIssueDashboardList extracts metric and viewBy parameters
  3. For metric=‘heatmap’ and viewBy=‘issueRedFlag’, it calls DashboardIssueUsecase.getIssueHeatmap
  4. The use case processes the request with the provided query parameters
  5. The controller returns the formatted result as the HTTP response

4.3 QC Dashboard Flow

flowchart TD
    A[Dashboard QC Router] --> B[getQCPerformanceResult]
    A --> C[getQCCustomResult]
    A --> D[downloadQCPerformance]
    A --> E[downloadQCCustom]
    
    B --> F[DashboardQCController.getQCPerformanceResult]
    C --> G[DashboardQCController.getQCCustomResult]
    D --> H[DashboardQCController.downloadQCPerformance]
    E --> I[DashboardQCController.downloadQCCustom]
    
    F --> J[DashboardQCUsecase.getQCPerformanceResult]
    G --> K[DashboardQCUsecase.getQCCustomResult]
    H --> L[DashboardQCUsecase.downloadQCReport]
    I --> M[DashboardQCUsecase.downloadQCCustomReport]

The QC Dashboard provides endpoints for retrieving QC (Quality Control) performance metrics and custom QC results, as well as downloading these reports.

Example Flow: GET /dashboard/qc/

  1. Request hits the router which calls getQCPerformanceResult middleware
  2. DashboardQCController.getQCPerformanceResult processes the request
  3. The controller creates a DashboardQCRequestQueryOptions object from the query parameters
  4. It calls DashboardQCUsecase.getQCPerformanceResult with the context, query, and pagination options
  5. The use case processes the request and returns the QC performance result
  6. The controller returns the formatted result as the HTTP response

4.4 Report Dashboard Flow

flowchart TD
    A[Dashboard Report Router] --> B[getReportDashboardList]
    A --> C[getReportDashboardDetail]
    A --> D[downloadReportDashboardList]
    A --> E[downloadReportDashboardListView]
    
    B --> F[DashboardReportController.getReportDashboardList]
    C --> G[DashboardReportController.getReportDashboardDetail]
    D --> H[DashboardReportController.downloadReportDashboardList]
    E --> I[DashboardReportController.downloadReportDashboardListView]
    
    F --> F1[DashboardReportUsecase.getMissedReportList]
    F --> F2[DashboardReportUsecase.getRCRList]
    F --> F3[DashboardReportUsecase.getAllReportList]
    F --> F4[DashboardReportUsecase.getReportCompletionTimeList]
    F --> F5[DashboardReportUsecase.getSubmittedReportList]
    F --> F6[DashboardReportUsecase.getReportTrendsChartDetail]
    F --> F7[DashboardReportUsecase.getDrillByReportStatus]
    F --> F8[DashboardReportUsecase.getDrillByReportType]
    
    G --> G1[DashboardReportUsecase.getRCRDetail]
    G --> G2[DashboardReportUsecase.getCompleteReportDetail]
    G --> G3[DashboardReportUsecase.getCompleteReportInsightDetail]
    
    H --> H1[DashboardReportUsecase.downloadReportSubmitted]
    H --> H2[DashboardReportUsecase.downloadReportMissed]
    H --> H3[DashboardReportUsecase.downloadReportRCR]
    H --> H4[DashboardReportUsecase.downloadReportList]
    
    I --> I1[DashboardReportUsecase.downloadReportListView]

Similar to the Issue Dashboard, the Report Dashboard has complex routing that depends on query parameters. The controllers use the ‘metric’ and ‘viewBy’ parameters to determine which use case methods to call.

Example Flow: GET /dashboard/[report](../Reports/ReportsOverview.md)/?metric=reportList&viewBy=rcr

  1. Request hits the router which calls getReportDashboardList middleware
  2. DashboardReportController.getReportDashboardList extracts metric and viewBy parameters
  3. For metric=‘reportList’ and viewBy=‘rcr’, it calls DashboardReportUsecase.getRCRList
  4. The controller also rearranges drill-by parameters to ensure correct hierarchy (site, department, user, questionnaire)
  5. The use case processes the request and returns the RCR (Report Completion Rate) list
  6. The controller returns the formatted result as the HTTP response

5. Implementation Details

5.1 Common Patterns

5.1.1 Request Handling

All request handling follows a similar pattern:

public async methodName({ context, payload }) {
    try {
        // Extract parameters
        const { metric, viewBy } = payload.query; // for GET or payload.data for POST
        
        // Create query options object
        const dashboardQuery = new DashboardRequestQueryOptions({ ...payload.query });
        
        // Call appropriate use case method based on parameters
        switch (metric) {
            case 'someMetric': {
                return await this.useCase.someMethod(context, dashboardQuery);
            }
            default: {
                throw new ErrorCode(errors.INVALID, `[methodName] metric ${metric} is invalid`);
            }
        }
    } catch (error) {
        // Error logging and handling
        log.error(error, 'methodName');
        throw new ErrorCode(error.code || errors.INTERNAL, error.message);
    }
}

This pattern ensures consistent error handling and parameter validation across all endpoints.

5.1.2 Middleware Usage

The routers use the middlewares.expressCallback wrapper to standardize controller method interfaces:

const getIssueDashboardList = middlewares.expressCallback(controller.getIssueDashboardList);
this._router.get('/', getIssueDashboardList);

This wrapper converts Express request/response objects into a more structured format for the controllers.

5.1.3 Error Handling

Error handling is standardized across the application with the ErrorCode class from the @nimbly-technologies/nimbly-common package:

try {
    // Code that might throw
} catch (error) {
    log.error(error, 'methodName');
    throw new ErrorCode(error.code || errors.INTERNAL, error.message);
}

This ensures consistent error responses with appropriate HTTP status codes.

5.2 Key Components

5.2.1 Dashboard Controllers

Controllers are responsible for:

  • Extracting and validating request parameters
  • Determining which use case method to call based on parameters
  • Error handling and response formatting

Each controller method typically follows this flow:

  1. Extract parameters from the request
  2. Validate parameters and create appropriate query objects
  3. Call the appropriate use case method
  4. Return the formatted result or handle errors

5.2.2 Dashboard Use Cases

Use cases implement the business logic for each endpoint. They handle:

  • Data retrieval and processing
  • Filtering and aggregation
  • Report generation
  • Domain-specific calculations

Use cases are defined by interfaces to ensure all required methods are implemented:

export interface IDashboardIssueUsecase {
    getIssueVOC: (ctx: Context<UserAuth>, query: DashboardRequestQueryOptions) => Promise<GetIssueVOCResponse>;
    getIssueHeatmap: (ctx: Context<UserAuth>, query: DashboardRequestQueryOptions) => Promise<GetIssueHeatmapResponse>;
    // Other methods...
}

5.2.3 Query Options Models

Models like DashboardRequestQueryOptions and DownloadDashboardRequestQueryOptions handle request parameter validation and transformation:

export class DashboardRequestQueryOptions implements IDashboardRequestQueryOptions {
    // Properties
    
    constructor(props: IDashboardRequestQueryOptions) {
        // Property validation and assignment
    }
    
    // Helper methods
}

These models ensure that request parameters are properly validated before being used by the use cases.

5.3 Dashboard Module Interactions

The Dashboard module interacts with several other parts of the API Statistics system:

  1. Authentication Middleware - Verifies user credentials and permissions
  2. Database Repositories - Retrieves and stores dashboard data
  3. Export Services - Generates downloadable reports in various formats
  4. Notification Services - Sends alerts based on dashboard metrics

These interactions ensure that the dashboard data is accurate, secure, and actionable.

6. Special Implementation Features

6.1 Dual GET/POST Support

Most endpoints support both GET and POST methods to accommodate different client requirements:

// GET method
this._router.get('/', getIssueDashboardList);
 
// POST method (V1)
this._router.post('/', getIssueDashboardListV1);

The POST methods (V1 versions) were added to better handle complex filtering and query parameters that might exceed URL length limits.

6.2 Drill-By Parameter Handling

Many dashboard endpoints support “drill-by” parameters that determine the data aggregation hierarchy:

const reArrangeDrillBy = (drillBy: DrillByEnum[]) => {
    const newDrillByQuery = [];
 
    if (!drillBy.length) return newDrillByQuery;
 
    if (drillBy.includes(DrillByEnum.SITE)) {
        newDrillByQuery.push(DrillByEnum.SITE);
    }
    if (drillBy.includes(DrillByEnum.DEPARTMENT)) {
        newDrillByQuery.push(DrillByEnum.DEPARTMENT);
    }
    // Other levels...
    
    return newDrillByQuery;
};

This ensures that data is aggregated in a logical hierarchy (e.g., site → department → user → questionnaire).

6.3 Download Functionality

The dashboard modules provide comprehensive download functionality for report generation:

public async downloadReportDashboardList({ context, payload }) {
    try {
        const dashboardQuery = new DownloadDashboardRequestQueryOptions({ ...payload.query });
        dashboardQuery.fieldName = reArrangeDownloadField(payload.query.groupBy, dashboardQuery.fieldName);
        const { metric } = payload.query;
 
        let res;
        switch (metric) {
            case 'reportSubmitted': {
                res = await this.dashboardReportUsecase.downloadReportSubmitted(context, dashboardQuery);
                break;
            }
            // Other cases...
        }
        return res;
    } catch (error) {
        log.error(error, 'downloadReportDashboardList');
        throw new ErrorCode(error.code || errors.INTERNAL, error.message);
    }
}

This functionality allows users to export dashboard data for offline analysis or reporting.

7. Key Data Flows

7.1 Dashboard Issue Metrics Flow

sequenceDiagram
    participant Client
    participant Router as Dashboard Issue Router
    participant Controller as Dashboard Issue Controller
    participant UseCase as Dashboard Issue Usecase
    participant Repository as Issue Repository
    participant DB as MongoDB

    Client->>Router: GET /dashboard/issue/?metric=issueChart
    Router->>Controller: getIssueDashboardList
    Controller->>Controller: Extract metric & viewBy
    Controller->>Controller: Create DashboardRequestQueryOptions
    Controller->>UseCase: getIssueTrendsChartDetail
    UseCase->>Repository: fetchIssueData
    Repository->>DB: Query issues collection
    DB->>Repository: Raw issue data
    Repository->>UseCase: Processed issue data
    UseCase->>UseCase: Calculate trends and metrics
    UseCase->>Controller: Formatted chart data
    Controller->>Router: JSON response
    Router->>Client: HTTP 200 with chart data

This flow shows how a request for issue trend chart data is processed through the system.

7.2 QC Performance Metrics Flow

sequenceDiagram
    participant Client
    participant Router as Dashboard QC Router
    participant Controller as Dashboard QC Controller
    participant UseCase as Dashboard QC Usecase
    participant Repository as QC Repository
    participant DB as MongoDB

    Client->>Router: GET /dashboard/qc/
    Router->>Controller: getQCPerformanceResult
    Controller->>Controller: Extract pagination params
    Controller->>Controller: Create DashboardQCRequestQueryOptions
    Controller->>UseCase: getQCPerformanceResult
    UseCase->>Repository: fetchQCData
    Repository->>DB: Query QC metrics collection
    DB->>Repository: Raw QC data
    Repository->>UseCase: Processed QC data
    UseCase->>UseCase: Calculate performance metrics
    UseCase->>Controller: Formatted performance data
    Controller->>Router: JSON response
    Router->>Client: HTTP 200 with performance data

This flow demonstrates how QC performance metrics are retrieved and processed.

7.3 Report Download Flow

sequenceDiagram
    participant Client
    participant Router as Dashboard Report Router
    participant Controller as Dashboard Report Controller
    participant UseCase as Dashboard Report Usecase
    participant Repository as Report Repository
    participant DB as MongoDB
    participant ExportService as Export Service

    Client->>Router: GET /dashboard/report/download?metric=reportSubmitted
    Router->>Controller: downloadReportDashboardList
    Controller->>Controller: Create DownloadDashboardRequestQueryOptions
    Controller->>Controller: Extract metric param
    Controller->>UseCase: downloadReportSubmitted
    UseCase->>Repository: fetchSubmittedReports
    Repository->>DB: Query reports collection
    DB->>Repository: Raw report data
    Repository->>UseCase: Processed report data
    UseCase->>ExportService: Generate report file
    ExportService->>UseCase: File URL or content
    UseCase->>Controller: Download response data
    Controller->>Router: Download response
    Router->>Client: HTTP 200 with file download

This flow illustrates how report download requests are processed, including file generation.

8. Summary

The API Statistics Dashboard Module provides a comprehensive set of endpoints for retrieving and analyzing various metrics related to issues, reports, and quality control. The module follows clean architecture principles with distinct layers for routing, controllers, use cases, and data access.

Key features of the Dashboard Module include:

  1. Comprehensive Metrics - A wide range of metrics for issues, reports, and QC
  2. Flexible Filtering - Support for various filter parameters including date ranges, sites, departments, users, and more
  3. Drill-Down Analysis - Hierarchical data aggregation for deeper insights
  4. Download Functionality - Export capabilities for offline analysis and reporting
  5. Dual GET/POST Support - Flexibility for different client requirements

The module is designed to be extensible, with new metrics and visualization types easily added to the existing framework. The consistent error handling and parameter validation ensure reliable operation even with complex filtering requirements.

9. Appendix: Code Samples

9.1 Router Configuration

// dashboard.issue.router.ts
export default class DashboardIssueRouter {
    public constructor(private _router: Router, controller: DashboardIssueController) {
        const getIssueDashboardList = middlewares.expressCallback(controller.getIssueDashboardList);
        const weeklyScoreMetrics = middlewares.expressCallback(controller.weeklyScoreMetrics);
        // Other middleware bindings...
 
        this._router.get('/', getIssueDashboardList);
        this._router.get('/list', findIssuesByEntityID);
        // Other routes...
 
        this._router.post('/', getIssueDashboardListV1);
        this._router.post('/weekly-completion-score', weeklyScoreMetrics);
        // Other POST routes...
    }
 
    public get router() {
        return this._router;
    }
}

9.2 Controller Method

// dashboard.issue.controller.ts
public async getIssueDashboardList({ context, payload }: GetIssueDashboardListParams) {
    try {
        const { metric, viewBy } = payload.query;
 
        const reArrangeDrillBy = (drillBy: DrillByEnum[]) => {
            // Implementation...
        };
 
        switch (metric) {
            case 'heatmap': {
                if (viewBy === 'issueRedFlag') {
                    return await this.dashboardIssueUsecase.getIssueHeatmap(
                        context,
                        new DashboardRequestQueryOptions({ ...payload.query }),
                    );
                }
                throw new ErrorCode(errors.INVALID, `[getIssueDashboardList] viewBy ${viewBy} is invalid`);
            }
            // Other cases...
            default: {
                throw new ErrorCode(errors.INVALID, `[getIssueDashboardList] metric ${metric} is invalid`);
            }
        }
    } catch (error) {
        log.error(error, 'getIssueDashboardList');
        throw new ErrorCode(error.code || errors.INTERNAL, error.message);
    }
}

9.3 Use Case Interface

// dashboard.issue.usecase.d.ts
export interface IDashboardIssueUsecase {
    getIssueVOC: (ctx: Context<UserAuth>, query: DashboardRequestQueryOptions) => Promise<GetIssueVOCResponse>;
    getIssueHeatmap: (ctx: Context<UserAuth>, query: DashboardRequestQueryOptions) => Promise<GetIssueHeatmapResponse>;
    getIssueDetails: (ctx: Context<UserAuth>, query: DashboardRequestQueryOptions) => Promise<IssueDetailResponse>;
    // Other methods...
}

9.4 Model Definition

// dashboardQueryOptions.ts
export interface IDashboardRequestQueryOptions {
    readonly startDate?: string;
    readonly endDate?: string;
    readonly sites?: string[];
    readonly departments?: string[];
    readonly users?: string[];
    readonly roles?: string[];
    readonly metric?: string;
    readonly viewBy?: string;
    readonly timezone?: string;
    readonly drillBy?: DrillByEnum[];
    readonly compareBy?: DrillByEnum;
    readonly compareValue?: string;
    readonly questionnaireTypes?: string[];
    readonly questionnaires?: string[];
    // Other properties...
}

10. Data Flow and Processing

10.1 Issue Dashboard Data Processing

The Issue Dashboard implements a complex data processing flow to transform raw database records into actionable metrics. Here’s a more detailed look at how data flows through the system for the issue metrics:

flowchart LR
    A[Raw Database Records] --> B[Data Retrieval Layer]
    B --> C[Data Transformation Layer]
    C --> D[Metrics Calculation Layer]
    D --> E[Data Aggregation Layer]
    E --> F[Response Formatting Layer]
    F --> G[API Response]
    
    subgraph "Data Retrieval Layer"
    B1[Query Builder]
    B2[Database Connector]
    B3[Query Executor]
    end
    
    subgraph "Data Transformation Layer"
    C1[Field Mapping]
    C2[Type Conversion]
    C3[Null Value Handling]
    end
    
    subgraph "Metrics Calculation Layer"
    D1[Score Calculation]
    D2[Trend Analysis]
    D3[Comparative Analysis]
    end
    
    subgraph "Data Aggregation Layer"
    E1[Grouping]
    E2[Sorting]
    E3[Pagination]
    end
    
    subgraph "Response Formatting Layer"
    F1[Structure Building]
    F2[Data Serialization]
    F3[Metadata Addition]
    end

Example Flow: Issue Heatmap Generation

For generating an issue heatmap, the data goes through the following steps:

  1. Query Building: The system constructs a MongoDB query based on filter parameters (date range, sites, departments, etc.)
  2. Data Retrieval: Raw issue records are fetched from the database
  3. Transformation: Raw data is transformed into a more usable format (dates are parsed, nulls are handled, etc.)
  4. Metrics Calculation: For each cell in the heatmap, the system calculates the metric value (e.g., issue count, severity score)
  5. Aggregation: Data is grouped by the axes of the heatmap (e.g., time periods on one axis, categories on the other)
  6. Response Formatting: The final heatmap data is structured in a format that the client can easily render

10.2 Report Dashboard Processing

The Report Dashboard implements several specialized processing flows for different types of reports:

10.2.1 RCR (Report Completion Rate) Calculation

// Pseudocode for RCR calculation
function calculateRCR(reports, filterCriteria) {
    const filteredReports = applyFilters(reports, filterCriteria);
    const groupedReports = groupByDrillCriteria(filteredReports, filterCriteria.drillBy);
    
    return groupedReports.map(group => {
        const totalReports = group.reports.length;
        const completedReports = group.reports.filter(r => r.status === 'completed').length;
        const rcr = totalReports > 0 ? (completedReports / totalReports) * 100 : 0;
        
        return {
            groupName: group.name,
            totalReports,
            completedReports,
            rcr,
            // Additional metrics...
        };
    });
}

The report trends chart processing involves time-series analysis to show how reporting metrics change over time:

  1. Time Period Division: The date range is divided into appropriate periods (days, weeks, months)
  2. Data Aggregation: Reports are grouped by time period and other drill-by parameters
  3. Metrics Calculation: For each time period, metrics like completion rate, submission count, and average completion time are calculated
  4. Trend Calculation: The system calculates trend indicators (up/down/flat) by comparing current period with previous periods
  5. Response Formatting: The data is structured as a time series that the client can easily chart

10.3 QC Dashboard Processing

The QC Dashboard implements quality control metrics processing:

10.3.1 QC Performance Calculation

// Pseudocode for QC performance calculation
function calculateQCPerformance(qcData, filterCriteria) {
    const filteredQCData = applyFilters(qcData, filterCriteria);
    const groupedQCData = groupByDrillCriteria(filteredQCData, filterCriteria.drillBy);
    
    return groupedQCData.map(group => {
        const totalChecks = group.checks.length;
        const passedChecks = group.checks.filter(c => c.result === 'pass').length;
        const performanceRate = totalChecks > 0 ? (passedChecks / totalChecks) * 100 : 0;
        
        return {
            groupName: group.name,
            totalChecks,
            passedChecks,
            performanceRate,
            // Additional metrics...
        };
    });
}

10.3.2 Custom QC Metrics

The system also supports custom QC metrics defined by clients:

  1. Custom Metric Definition: Clients define custom metrics with specific calculation rules
  2. Data Collection: Raw QC data is collected based on filter criteria
  3. Custom Calculation: The system applies the custom calculation rules to the data
  4. Aggregation: Results are grouped by drill-by parameters
  5. Response Formatting: The custom metrics are formatted for API response

11. Security and Authentication

The dashboard module relies on authentication middleware to ensure that only authorized users can access sensitive metrics:

11.1 Authentication Flow

sequenceDiagram
    participant Client
    participant Router
    participant AuthMiddleware
    participant Controller
    
    Client->>Router: Request with auth token
    Router->>AuthMiddleware: Pass request
    AuthMiddleware->>AuthMiddleware: Validate token
    AuthMiddleware->>AuthMiddleware: Check permissions
    AuthMiddleware->>Controller: Authorized request with user context
    Controller->>Controller: Process request
    Controller->>Router: Response
    Router->>Client: HTTP response

11.2 Permission-Based Access Control

The dashboard module implements permission-based access control to ensure users can only access data they are authorized to view:

// Pseudocode for permission-based access control
function applyPermissionFilters(query, userContext) {
    if (!userContext.hasPermission('VIEW_ALL_SITES')) {
        query.sites = intersection(query.sites, userContext.authorizedSites);
    }
    
    if (!userContext.hasPermission('VIEW_ALL_DEPARTMENTS')) {
        query.departments = intersection(query.departments, userContext.authorizedDepartments);
    }
    
    // Apply other permission-based filters...
    
    return query;
}

This ensures that users can only access data for sites, departments, and other entities they are authorized to view.

12. Performance Optimization

The dashboard module implements several performance optimizations to handle large datasets efficiently:

12.1 Query Optimization

// Pseudocode for query optimization
function optimizeQuery(query, filterCriteria) {
    // Add appropriate indexes
    query.hint({ site: 1, department: 1, date: 1 });
    
    // Limit fields retrieved
    query.select('field1 field2 field3');
    
    // Use aggregation pipeline for complex calculations
    if (needsComplexCalculation(filterCriteria)) {
        return buildAggregationPipeline(filterCriteria);
    }
    
    return query;
}

12.2 Caching Strategy

The system implements caching for frequently accessed dashboard data:

// Pseudocode for dashboard caching
async function getCachedDashboardData(cacheKey, fetchFn) {
    const cachedData = await cache.get(cacheKey);
    
    if (cachedData) {
        return cachedData;
    }
    
    const freshData = await fetchFn();
    await cache.set(cacheKey, freshData, TTL_IN_SECONDS);
    
    return freshData;
}

12.3 Pagination and Chunking

For large datasets, the system implements pagination and chunking:

// Pseudocode for paginated dashboard data
function getPaginatedData(query, paginationOptions) {
    const { page, limit } = paginationOptions;
    const skip = (page - 1) * limit;
    
    return {
        data: query.skip(skip).limit(limit),
        pagination: {
            page,
            limit,
            total: getTotalCount(query)
        }
    };
}

13. Error Handling and Logging

The dashboard module implements comprehensive error handling and logging:

13.1 Error Classification

Errors are classified into several categories:

  • Validation Errors: Invalid request parameters
  • Authentication Errors: Missing or invalid authentication
  • Authorization Errors: Insufficient permissions
  • Business Logic Errors: Violations of business rules
  • Technical Errors: Database errors, timeouts, etc.

13.2 Error Handling Pattern

// Error handling pattern
try {
    // Business logic
} catch (error) {
    // Log the error with context
    log.error(error, 'methodName', { additionalContext });
    
    // Translate to appropriate ErrorCode
    if (error instanceof ValidationError) {
        throw new ErrorCode(errors.INVALID, error.message);
    } else if (error instanceof AuthError) {
        throw new ErrorCode(errors.UNAUTHORIZED, error.message);
    } else {
        throw new ErrorCode(error.code || errors.INTERNAL, error.message);
    }
}

13.3 Logging Strategy

The system implements structured logging for better troubleshooting:

// Structured logging
log.info('Processing dashboard request', {
    user: context.user.id,
    metric: query.metric,
    viewBy: query.viewBy,
    dateRange: { start: query.startDate, end: query.endDate },
    filterCriteria: { 
        sites: query.sites, 
        departments: query.departments 
    }
});

15. Conclusion

The API Statistics Dashboard Module provides a robust framework for retrieving, analyzing, and visualizing various metrics related to [issues](../Issue Tracker/IssueTrackerOverview.md), reports, and quality control. The module follows clean architecture principles and implements best practices for security, performance, and error handling.

The module’s flexible design allows for easy extension with new metrics, visualization types, and integrations with other systems. The consistent API structure and comprehensive documentation make it easy for clients to integrate with the dashboard functionality.

By providing actionable insights through well-structured dashboards, the API Statistics system helps organizations monitor performance, identify [issues](../Issue Tracker/IssueTrackerOverview.md), and make data-driven decisions to improve quality and efficiency.

This documentation provides a comprehensive technical overview of the API Statistics Dashboard Module, including architecture, function flows, and implementation details. It serves as a reference for developers working with the dashboard functionality and as a guide for understanding the system’s capabilities and architecture.

Graph View

Backlinks