Feat dashboard analytics

[RUKAYAT-CODER]

📊 Create Dashboard Analytics and Statistics API

Module: Analytics / Reporting
Type: Feature

---

📖 Overview

This PR introduces a comprehensive analytics and statistics API to power dashboard visualizations, reporting, and data-driven insights across the platform. The API provides real-time and aggregated statistics, trends, distributions, and predictive insights while ensuring high performance through caching and optimized queries.

The solution is designed to scale with large datasets and support role-based access to analytics data.

---

🎯 Goals

• Provide accurate, real-time dashboard statistics
• Support trend and distribution data for charts and visualizations
• Enable department-, location-, and user-specific analytics
• Deliver performant responses through caching and optimized queries
• Support advanced insights such as forecasting and anomaly detection

---

🌐 API Endpoints

Dashboard Analytics

• GET /api/v1/analytics/dashboard — Main dashboard statistics
• GET /api/v1/analytics/asset-stats — Asset-specific statistics
• GET /api/v1/analytics/trends — Trend data for charts
• GET /api/v1/analytics/distribution — Asset distribution data
• GET /api/v1/analytics/top-assets — Highest-value assets
• GET /api/v1/analytics/alerts — Assets requiring attention

---

Department Analytics

• GET /api/v1/analytics/departments/:id — Department analytics
• GET /api/v1/analytics/departments/comparison — Cross-department comparison

---

Location Analytics

• GET /api/v1/analytics/locations/:id — Location-specific analytics
• GET /api/v1/analytics/locations/utilization — Utilization rates

---

User Analytics

• GET /api/v1/analytics/users/:id — User asset assignment history
• GET /api/v1/analytics/users/activity — User activity statistics

---

Time-Based Analytics

• GET /api/v1/analytics/timeline — Asset registrations over time
• GET /api/v1/analytics/forecast — Predictive analytics (asset needs)

---

📦 Response Structures

Dashboard Statistics

• Asset overview and value totals
• Month-over-month percentage changes
• Asset breakdowns by status and condition
• Top categories and departments
• Recent activity feed
• Actionable alerts (maintenance, warranty, transfers)

Trends Data

• Asset registrations over time
• Total asset value growth
• Transfer volume trends

Distribution Data

• Asset distribution by category, department, location, and status
• Percentages always total 100%

---

🧠 Business Logic

• Real-time calculations with intelligent caching
• Date range filtering for all analytics endpoints
• Role-based access control:
  • Users see only authorized department data
• Period-over-period percentage calculations
• Efficient aggregation using database views and materialized views
• Multi-currency support with conversion to base currency
• Predictive analytics for asset demand forecasting
• Anomaly detection (spikes in transfers or asset value)
• Asset utilization rate calculations
• Asset lifecycle cost tracking (purchase + maintenance)

---

🧮 Caching Strategy

• Dashboard stats: 5-minute TTL
• Trend data: 1-hour TTL
• Distribution data: 15-minute TTL
• Redis used for cache storage
• Automatic cache invalidation on relevant data updates

---

⚡ Performance Optimizations

• Database indexes on date and foreign key columns
• Materialized views for complex aggregations
• Scheduled refresh jobs (cron)
• TypeORM query builder for optimized queries
• SQL window functions for trend analysis
• Pagination for large result sets
• Query result caching
• JSON aggregation optimizations
• Connection pooling
• Response compression for large payloads
• Rate limiting to prevent abuse

---

🔧 Technical Implementation

• ORM: TypeORM (query builder)
• Database: Views & materialized views
• Caching: Redis
• Jobs: Scheduled tasks (cron)
• Security: Role-based data filtering, rate limiting

---

🧪 Testing

• Unit tests for aggregation logic
• Validation of percentage and trend calculations
• Cache hit/miss and invalidation scenarios
• Role-based access enforcement
• Large dataset performance tests

---

✅ Acceptance Criteria

• Dashboard API returns accurate statistics
• Percentage calculations are correct
• Trend data supports configurable date ranges
• Distribution totals equal 100%
• Cache invalidation works correctly
• Dashboard response time < 500ms
• Date range filters function correctly
• Role-based filtering enforces data access
• Aggregations match raw data counts
• API handles large datasets efficiently

---

🚀 Impact

This PR delivers a high-performance, analytics-ready API that enables rich dashboards, actionable insights, and scalable reporting capabilities for data-driven decision making.

close #388

[vercel]

@RUKAYAT-CODER is attempting to deploy a commit to the naijabuz's projects Team on Vercel.

A member of the Team first needs to authorize it.