# Dashboard

The Capsule Security dashboard provides real-time insights into your AI agent ecosystem through customizable widgets and interactive visualizations.

## Dashboard Overview

The dashboard is organized into two main sections:

1. **Risk Widgets**: Security and compliance metrics
2. **Usage Widgets**: Operational and performance metrics


## Risk Widgets

### Non High-Severity Agents

A vertical segmented bar showing the distribution of agents without high-severity issues:

- Visual representation of security posture
- Quick identification of compliant agents
- Percentage of safe vs. at-risk agents


### Agents by Severity

Horizontal stacked bar chart displaying agent distribution by severity level:

- **CRITICAL**: Red - Immediate attention required
- **HIGH**: Orange - Urgent issues
- **MEDIUM**: Yellow - Standard priority
- **LOW**: Green - Minor concerns


Interactive features:

- Click any severity level to filter the agents page
- Hover for detailed counts
- Badge-style legend for clarity


### Agent Accessibility

Statistical chart showing agent access levels:

- **PUBLIC**: Openly accessible agents
- **TENANT**: Organization-restricted agents
- **LIMITED**: Highly restricted agents


Features:

- Progress bar visualization
- Click to navigate to filtered agent list
- Real-time percentage calculations


### Risk by Category Breakdown

Compact metric bar displaying risk distribution:

Categories with visual indicators:

- **Supply Chain**: Cable icon (red) - Third-party risks
- **Data**: Database icon (purple) - Data security issues
- **Compliance**: Globe icon (orange) - Regulatory concerns
- **Integrity**: Scale icon (blue) - Data integrity
- **Access**: Snowflake icon (dark red) - Access control
- **Misc**: Triangle icon (yellow) - Other issues


## Usage Widgets

### Agent Sessions Timeline

Line chart showing agent activity over time:

- Session frequency trends
- Peak usage identification
- Historical comparison
- Configurable time ranges (24h, 7d, 30d, 90d)


### Tool Invocations

Pie chart displaying tool usage distribution:

- Most frequently used tools
- Tool type breakdown
- Interactive segments - click to filter agents
- Custom tool icons in legend
- Percentage and count display


### Agents by Environment

Horizontal stacked bar showing environment distribution:

- **Production**: Live agents
- **Staging**: Pre-production testing
- **Development**: In-development agents


Interactive filtering by clicking environment segments.

### Top 5 Agent Owners

Metric bar highlighting the most active agent owners:

- Owner avatars with names
- Agent count per owner
- Click to view owner's agents
- Useful for identifying key stakeholders


## Widget Customization

### Widget Sizes

Widgets support responsive sizing:

- **Small**: 1x1 grid unit
- **Medium**: 2x1 grid units
- **Large**: 2x2 grid units
- **Full**: Full width


### Layout Configuration

The dashboard uses a responsive grid system:


```typescript
widget('widget-id')
  .title('Widget Title')
  .size({
    default: 'medium',
    tablet: 'medium',
    mobile: 'full'
  })
  .aspectRatio('16/9')
  .minHeight('fit-content')
  .build()
```

## Data Sources

Dashboard widgets pull data from specialized hooks:

### Risk Data Hooks

- `useNonHighSeverityAgents()`: Agent safety metrics
- `useAgentsSeverity()`: Severity distribution
- `useAgentsAccess()`: Access level breakdown
- `useRiskByCategory()`: Categorized risk analysis


### Usage Data Hooks

- `useAgentSessionsTimeline()`: Historical session data
- `useToolsInvocationCount()`: Tool usage statistics
- `useAgentEnvironments()`: Environment distribution
- `useTopAgentOwners()`: Owner activity metrics


## Interactive Features

### Click-Through Navigation

Most widgets support click-through to filtered views:


```javascript
// Example: Clicking on HIGH severity
navigate('/agents?severity=HIGH')

// Example: Clicking on a specific tool
navigate('/agents?tools=database')

// Example: Clicking on an owner
navigate('/agents?ownership=user@example.com')
```

### Real-Time Updates

Dashboard data refreshes automatically:

- Default refresh: Every 60 seconds
- Manual refresh: Pull-to-refresh on mobile
- WebSocket updates for critical alerts


### Export Capabilities

Export dashboard data in multiple formats:

- **PDF**: Full dashboard snapshot
- **CSV**: Raw data export
- **JSON**: Structured data export
- **Image**: Widget screenshots


## Performance Optimization

### Data Caching

- Widget data cached for 60 seconds
- Stale-while-revalidate strategy
- Background refresh for smooth UX


### Lazy Loading

- Widgets load on viewport entry
- Progressive data fetching
- Optimized for mobile devices


## Custom Widgets

### Creating Custom Widgets


```typescript
import { widget } from '@capsulesecurity/ui';

const customWidget = widget('custom-metric')
  .title('Custom Metric')
  .size({ default: 'medium' })
  .useData(useCustomData)
  .content((props) => (
    <CustomVisualization {...props} />
  ))
  .build();
```

### Widget API

Each widget receives:

- `data`: Processed data from hook
- `loading`: Loading state
- `error`: Error state
- `refetch`: Manual refresh function


## Dashboard Best Practices

### Information Architecture

1. **Priority Placement**
  - Critical metrics above the fold
  - Risk widgets before usage widgets
  - Interactive elements prominently displayed
2. **Visual Hierarchy**
  - Larger widgets for key metrics
  - Color coding for severity
  - Clear labels and legends
3. **Responsive Design**
  - Mobile-first approach
  - Touch-friendly interactions
  - Appropriate widget sizing per device


### Performance Tips

1. **Data Management**
  - Use pagination for large datasets
  - Implement virtual scrolling
  - Cache frequently accessed data
2. **Rendering Optimization**
  - Memoize expensive calculations
  - Use React.memo for widget components
  - Implement windowing for lists


## Troubleshooting

### Common Issues

1. **Widgets Not Loading**
  - Check network connectivity
  - Verify API permissions
  - Review browser console for errors
2. **Incorrect Data**
  - Clear browser cache
  - Force data refresh
  - Check data source filters
3. **Performance Issues**
  - Reduce number of visible widgets
  - Check browser performance metrics
  - Consider data aggregation settings


### Dashboard API

Access raw dashboard data programmatically:


```javascript
GET /api/v1/dashboard/widgets?widgets=agents-by-severity,tool-invocation-count

Response:
{
  "agents-by-severity": {
    "data": [...],
    "updatedAt": "2024-01-15T14:30:00Z"
  },
  "tool-invocation-count": {
    "data": [...],
    "updatedAt": "2024-01-15T14:30:00Z"
  }
}
```