# ExESDBDashboard

**Advanced Dashboard Package for EventStore Cluster Monitoring**

ExESDBDashboard provides composable, real-time dashboard components for monitoring and managing EventStore clusters in Phoenix applications. Features both basic cluster monitoring and an advanced admin dashboard with comprehensive analytics.

## Features

### 🏢 Advanced Admin Dashboard
- **Multi-tab Interface**: Overview, Streams, Performance, and Logs tabs
- **Real-time Monitoring**: Live updates via Phoenix PubSub
- **Dark Mode Support**: Toggle between light and dark themes
- **Responsive Design**: Works on desktop, tablet, and mobile devices
- **Stream Analytics**: Monitor stream activity, event counts, and top performers
- **Performance Metrics**: Track response time, throughput, error rates, and resource usage
- **System Logs**: View and filter system logs by level (error, warning, info, debug)
- **Auto-refresh**: Configurable automatic data refresh with pause/resume controls

### 📊 Basic Cluster Dashboard
- **Cluster Health**: Real-time health status with visual indicators
- **Node Management**: Monitor connected nodes and their status
- **Store Statistics**: Track EventStore instances and their metrics
- **Stream Counts**: View total streams across all stores
- **Subscription Monitoring**: Track active subscriptions

### 🎨 Styling & UI
- **Professional Design**: Modern, clean interface with consistent theming
- **CSS Custom Properties**: Easily customizable colors and styling
- **Mobile-first**: Responsive grid layouts and touch-friendly controls
- **Accessibility**: Proper focus states and semantic HTML
- **Animation**: Smooth transitions and loading states

## Installation

### From Local Path (Development)

Add `ex_esdb_dashboard` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:ex_esdb_dashboard, path: "../beam-campus/ex-esdb-dashboard/package"},
    {:phoenix_live_view, "~> 0.18.0"},  # Required
    {:ex_esdb_gater, "~> 0.1.0"}        # For cluster integration
  ]
end
```

### From Hex (When Published)

```elixir
def deps do
  [
    {:ex_esdb_dashboard, "~> 0.1.0"}
  ]
end
```

## Quick Start

### 1. Add Routes to Your Phoenix Router

```elixir
# lib/my_app_web/router.ex
defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  import ExESDBDashboard  # Import dashboard routing macro
  
  # ... your other routes
  
  scope "/admin" do
    pipe_through :browser
    dashboard_routes()  # Adds /cluster, /admin routes
  end
end
```

This adds the following routes:
- `/admin/` - Basic cluster dashboard (ClusterLive)
- `/admin/cluster` - Basic cluster dashboard (ClusterLive) 
- `/admin/admin` - Advanced admin dashboard (AdminLive)

### 2. Include Dashboard CSS

#### Option A: Import in your app.scss

```scss
// assets/css/app.scss
@import "../deps/ex_esdb_dashboard/priv/static/css/dashboard.css";
```

#### Option B: Copy CSS file to your assets

```bash
cp deps/ex_esdb_dashboard/priv/static/css/dashboard.css assets/css/
```

Then include it in your CSS build process.

### 3. Configure PubSub (Optional)

For real-time updates, ensure Phoenix.PubSub is configured in your application:

```elixir
# lib/my_app/application.ex
children = [
  {Phoenix.PubSub, name: MyApp.PubSub},
  # ... other children
]
```

## Usage Examples

### Individual Components

You can mount individual dashboard components instead of using the routing macro:

```elixir
# In your router
live "/cluster-status", ExESDBDashboard.ClusterLive
live "/admin-dashboard", ExESDBDashboard.AdminLive
```

### Embedding Components

Embed dashboard components in your existing LiveViews:

```elixir
defmodule MyAppWeb.AdminLive do
  use MyAppWeb, :live_view
  
  def render(assigns) do
    ~H"""
    <div class="admin-page">
      <h1>System Administration</h1>
      
      <!-- Embed cluster status widget -->
      <.live_component 
        module={ExESDBDashboard.ClusterStatus} 
        id="cluster-status"
      />
      
      <!-- Your other admin content -->
    </div>
    """
  end
end
```

### Custom Styling

Override CSS custom properties to match your app's theme:

```css
/* In your app.css */
:root {
  --dashboard-primary: #your-brand-color;
  --dashboard-success: #your-success-color;
  --dashboard-warning: #your-warning-color;
  --dashboard-danger: #your-error-color;
}

/* Dark mode overrides */
@media (prefers-color-scheme: dark) {
  :root {
    --dashboard-bg: #1a1a1a;
    --dashboard-white: #2d2d2d;
    /* ... other dark mode colors */
  }
}
```

## API Reference

### Main Module Functions

```elixir
# Get cluster data programmatically
ExESDBDashboard.get_cluster_data()
# => %{nodes: [...], stores: [...], total_streams: 42, cluster_health: :healthy}

# Individual data functions
ExESDBDashboard.cluster_health()    # => :healthy | :degraded | :unhealthy
ExESDBDashboard.cluster_nodes()     # => [%{name: :node1, status: :connected, ...}]
ExESDBDashboard.cluster_stores()    # => [%{id: "store1", stream_count: 10, ...}]
ExESDBDashboard.total_streams()     # => 42
```

### Component References

```elixir
# Get LiveView component modules
ExESDBDashboard.cluster_live_component()     # => ExESDBDashboard.ClusterLive
ExESDBDashboard.admin_live_component()       # => ExESDBDashboard.AdminLive
ExESDBDashboard.cluster_status_component()   # => ExESDBDashboard.ClusterStatus
```

## Advanced Features

### Real-time Updates

The dashboard subscribes to PubSub topics for real-time updates:

- `"cluster_health_updates"` - Health status changes
- `"cluster_lifecycle_events"` - Node joins/leaves, store changes
- `"system_events"` - General system events
- `"connection_status"` - Connection state changes

Publish to these topics from your application:

```elixir
# Broadcast health updates
Phoenix.PubSub.broadcast(
  MyApp.PubSub, 
  "cluster_health_updates", 
  {:cluster_health_update, :healthy}
)

# Broadcast system events
Phoenix.PubSub.broadcast(
  MyApp.PubSub,
  "system_events",
  {:system_event, %{type: "backup_completed", message: "Database backup finished"}}
)
```

### Performance Monitoring

The admin dashboard includes performance metrics tracking:

- **Response Time**: Average API response time
- **Throughput**: Requests/events per second
- **Error Rate**: Percentage of failed operations
- **Memory Usage**: Current memory consumption
- **Trend Indicators**: Up/down/stable trends for each metric

### Log Monitoring

System logs with filtering capabilities:

- Filter by log level (all, error, warning, info, debug)
- Real-time log streaming
- Formatted timestamps and structured display
- Color-coded log levels

## Configuration

### Environment Variables

```elixir
# config/config.exs
config :ex_esdb_dashboard,
  # Update interval for auto-refresh (milliseconds)
  update_interval: 5_000,
  # Maximum number of log entries to keep
  max_log_entries: 100,
  # Maximum number of activity entries
  max_activity_entries: 20,
  # PubSub module to use
  pubsub: MyApp.PubSub
```

### Theme Customization

The dashboard uses CSS custom properties for easy theming:

```css
:root {
  /* Primary colors */
  --dashboard-primary: #2563eb;
  --dashboard-success: #059669;
  --dashboard-warning: #d97706;
  --dashboard-danger: #dc2626;
  
  /* Background colors */
  --dashboard-bg: #f9fafb;
  --dashboard-white: #ffffff;
  --dashboard-border: #e5e7eb;
  
  /* Text colors */
  --dashboard-gray-dark: #374151;
  --dashboard-gray: #6b7280;
  
  /* Layout */
  --dashboard-radius: 0.5rem;
  --dashboard-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1);
}
```

## Requirements

- **Elixir**: >= 1.12
- **Phoenix**: >= 1.6
- **Phoenix LiveView**: >= 0.18
- **ExESDBGater**: For cluster integration (optional)

### Host Application Requirements

Your Phoenix application must have:

1. **Phoenix LiveView** configured and running
2. **Phoenix.PubSub** configured (for real-time updates)
3. **ExESDBGater.System** started in supervision tree (for cluster data)

## Development

### Setup

```bash
git clone https://github.com/beam-campus/ex-esdb-dashboard.git
cd ex-esdb-dashboard/package
mix deps.get
mix test
```

### Running Tests

```bash
mix test
mix test --cover
```

### Building Documentation

```bash
mix docs
open doc/index.html
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Changelog

### v0.2.0 (2025-08-16)
- ✨ **NEW**: Advanced Admin Dashboard with multi-tab interface
- ✨ **NEW**: Dark mode support with theme toggle
- ✨ **NEW**: Stream analytics and performance monitoring
- ✨ **NEW**: System logs with filtering capabilities
- ✨ **NEW**: Real-time updates via PubSub integration
- ✨ **NEW**: Responsive design for mobile devices
- ✨ **NEW**: Auto-refresh with pause/resume controls
- 🎨 Enhanced CSS styling with custom properties
- 🎨 Professional UI design with animations
- 📱 Mobile-first responsive layout
- ♿ Improved accessibility and focus management

### v0.1.0 (Initial Release)
- 📊 Basic cluster dashboard (ClusterLive)
- 🏥 Cluster health monitoring
- 🖥️ Node status tracking
- 🗄️ Store statistics display
- 📈 Stream and subscription counts
- 🎨 Basic CSS styling

## Support

For questions, issues, or contributions:

- **GitHub Issues**: [Report bugs or request features](https://github.com/beam-campus/ex-esdb-dashboard/issues)
- **Documentation**: [View full documentation](https://hexdocs.pm/ex_esdb_dashboard)
- **Community**: Join the Elixir EventSourcing community discussions