> ## Documentation Index
> Fetch the complete documentation index at: https://lopiv2-invenicum-25.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboard & Analytics

> Real-time statistics, market value tracking, and inventory insights

## Overview

The Invenicum dashboard provides a comprehensive view of your inventory health, financial value, and operational metrics. Track everything from total asset counts to market value trends in a single, real-time interface.

> **Live Statistics**
>
> Real-time counts of containers, items, and low-stock alerts

> **Financial Tracking**
>
> Aggregate market value across your entire inventory

> **Loan Insights**
>
> Monitor expiring loans and most-borrowed items

> **Actionable Alerts**
>
> Identify low-stock items and overdue returns instantly

## Dashboard Components

### Overview Statistics

The top of the dashboard displays key metrics (lib/data/models/dashboard\_stats.dart):

**Inventory**

* **Total Containers**: Number of organizational units
* **Total Asset Types**: Distinct categories across all containers
* **Total Items**: Aggregate count of all inventory entries
* **Items Pending**: Items with incomplete data or requiring action

**Financial**

* **Total Market Value**: Sum of all items' market values
* **Currency Breakdown**: Multi-currency support with conversion rates
* **Value by Container**: See which locations hold the most value

**Operational**

* **Low Stock Items**: Count of items below minimum threshold
* **Active Loans**: Currently loaned items
* **Loans Expiring Today**: Items due back today

**Technical Implementation** (lib/data/services/dashboard\_service.dart:20):

```dart theme={null}
DashboardService.getGlobalStats()
// GET /dashboard/stats
// Returns: DashboardStats object with all metrics
```

### Low Stock Alerts

Items where `quantity < minStock` appear in the Low Stock widget.

**Example:**

```
Item: "USB-C Cables"
Current Quantity: 3
Minimum Stock: 10
→ Appears in Low Stock (7 units short)
```

> [!TIP]
>
> Click on any low-stock item to immediately edit and increase quantity, or create a purchase order reminder.

### Loans Expiring Today

Displays active loans with `expectedReturnDate == today` (lib/data/models/dashboard\_stats.dart:13):

* Borrower name
* Item name
* Quantity loaned
* Quick "Mark as Returned" action

> [!NOTE]
>
> This widget uses server-side date comparison to account for timezone differences between users.

### Top Loaned Items

Shows items with the highest loan frequency (lib/data/models/dashboard\_stats.dart:12):

```
1. Dell Latitude 5520 (23 loans)
2. Projector - Epson EB-X41 (18 loans)
3. Folding Table (15 loans)
```

Use this to identify:

* High-demand assets (consider buying more)
* Items experiencing heavy use (monitor for wear)
* Popular equipment for prioritized maintenance

## Market Value Tracking

Invenicum tracks the financial value of your inventory over time.

### How It Works

1. **Set Market Value**: Enter `marketValue` and `currency` when creating/editing items (lib/data/models/inventory\_item.dart:68)
2. **Automatic Totaling**: Backend sums all items to calculate `totalMarketValue` (lib/data/services/inventory\_item\_service.dart:305)
3. **Price History**: Every value change is logged with timestamp (lib/data/models/inventory\_item.dart:65)
4. **Dashboard Display**: Total value appears in the financial overview widget

**1. Add Market Value to Item**

Edit an item and enter current market price (e.g., 1299.99) and currency (e.g., USD).

**2. Save & Track**

System records this as a price history point with today's date.

**3. View Totals**

Dashboard automatically aggregates values across all items.

**4. Analyze Trends**

Click "Value Over Time" to see portfolio performance charts.

### Price History

Each item maintains a history of market value changes (lib/data/models/inventory\_item.dart:65):

```json theme={null}
"priceHistory": [
  {
    "value": 1299.99,
    "currency": "USD",
    "date": "2024-01-15T10:30:00Z"
  },
  {
    "value": 1199.99,
    "currency": "USD",
    "date": "2024-02-10T14:20:00Z"
  }
]
```

**Accessing Price History** (lib/data/services/inventory\_item\_service.dart:325):

```dart theme={null}
InventoryItemService.getItemPriceHistory(itemId)
// GET /items/{itemId}/price-history
// Returns: List<PriceHistoryPoint>
```

> [!TIP]
>
> Use price history to track depreciation for accounting purposes or spot market trends for collectibles.

### UPC/Barcode Market Sync

For items with barcodes, Invenicum can sync market values from external databases (lib/data/services/inventory\_item\_service.dart:346):

**1. Add Barcode to Item**

Enter UPC/EAN code in the barcode field.

**2. Click 'Sync Market Value'**

Found in item actions menu.

**3. Automatic Lookup**

Invenicum queries pricing APIs for current market rates.

**4. Review & Confirm**

System shows suggested value—confirm to update.

> [!WARNING]
>
> Market value sync requires a valid UPC code and active internet connection. Not all products have pricing data available.

## Analytics & Reporting

### Available Reports

> **Inventory Valuation**
>
> Total market value by container, asset type, or location.

> **Stock Movement**
>
> Track quantity changes over time—identify shrinkage or growth.

> **Loan Activity**
>
> Historical loan data—who borrows most, which items, return rates.

> **Low Stock Trends**
>
> Predict when items will hit minimum stock based on usage patterns.

### Exporting Data

All dashboard metrics can be exported:

1. **CSV Export**: Spreadsheet-compatible format for Excel/Google Sheets
2. **PDF Reports**: Formatted summaries for stakeholders
3. **API Access**: Programmatic access to all statistics

**Example CSV Export:**

```csv theme={null}
Container,Asset Type,Item Count,Total Value,Low Stock Count
Warehouse A,Laptops,45,57498.55,3
Warehouse A,Monitors,82,16400.00,0
Office B,Chairs,120,18000.00,12
```

## Customizing Your Dashboard

### Widget Configuration

**1. Enter Edit Mode**

Click the "Customize Dashboard" button (top-right).

**2. Add/Remove Widgets**

Toggle visibility for each metric card.

Available widgets:

* Total containers
* Total items
* Market value
* Low stock alerts
* Loans expiring today
* Top loaned items

**3. Rearrange Layout**

Drag and drop widgets to your preferred positions.

**4. Save Layout**

Changes persist across sessions and devices.

### Setting Refresh Intervals

Dashboard data refreshes automatically:

* **Default**: Every 5 minutes
* **On Action**: Immediately after creating/editing items
* **Manual**: Pull-to-refresh gesture on mobile

Configure in Settings → Dashboard → Refresh Rate.

## Use Cases

> **Executive Reporting**
>
> Export monthly valuation reports for finance teams.

> **Procurement Planning**
>
> Use low stock trends to automate purchase orders.

> **Asset Audits**
>
> Compare dashboard totals with physical counts during audits.

> **Budget Forecasting**
>
> Track value depreciation to predict replacement costs.

## Performance Optimization

For large inventories (10,000+ items), dashboard loading can slow down. Optimizations:

1. **Container Filtering**: View stats for specific containers instead of global
2. **Date Range Limits**: Restrict price history queries to recent months
3. **Aggregation Caching**: Backend caches totals for 5 minutes
4. **Lazy Loading**: Widgets load independently—critical data appears first

> [!NOTE]
>
> The backend uses efficient aggregation queries to calculate totals without loading all items into memory (lib/data/services/dashboard\_service.dart).

## Best Practices

> **Daily Reviews**
>
> Check dashboard each morning for new low-stock alerts and expiring loans.

> **Monthly Valuations**
>
> Update market values on high-value items monthly for accurate reporting.

> **Alert Thresholds**
>
> Set `minStock` conservatively to avoid rush orders.

> **Historical Comparisons**
>
> Export dashboard stats monthly to track portfolio growth over quarters/years.

## Troubleshooting

### Dashboard Shows Zero Items

**Cause**: No items added yet, or data sync issue

**Solution**: Verify items exist in at least one container. Try manual refresh.

### Market Value Not Updating

**Cause**: Price changes don't immediately trigger dashboard refresh

**Solution**: Wait 5 minutes for next auto-refresh, or force refresh manually.

### Loans Expiring Today Shows Old Loans

**Cause**: Timezone mismatch between server and client

**Solution**: Check Settings → Time Zone. Ensure server and client agree on current date.

## API Reference

See the API documentation for:

* Dashboard Service - Statistics and analytics API
* Dashboard Stats Model - Complete stats data structure
* Price History Endpoint - Historical price data
* Total Market Value Endpoint - Aggregate collection value


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.