RubyGems - rails_error_dashboard - Versions diffs - 0.1.0 → 0.1.3 - Mend

rails_error_dashboard 0.1.0 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (95) hide show

data/README.md CHANGED Viewed

@@ -4,840 +4,438 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Tests](https://github.com/AnjanJ/rails_error_dashboard/workflows/Tests/badge.svg)](https://github.com/AnjanJ/rails_error_dashboard/actions)
-> **⚠️ BETA SOFTWARE**: This gem is currently in beta and under active development. While functional and tested, the API and features may change before v1.0.0. Use in production at your own discretion.
+## Self-hosted Rails error monitoring — free, forever.
-> **A beautiful error tracking dashboard for Rails applications and their frontends**
+**Own your errors. Own your stack. Zero monthly fees.**
-Rails Error Dashboard provides a complete error tracking and alerting solution for Rails backends AND frontend/mobile apps (React, React Native, Vue, Angular, Flutter, etc.). Features include: modern UI, multi-channel notifications (Slack + Email), real-time analytics, platform detection (iOS/Android/Web/API), and optional separate database support. Built with Rails 7+ error reporting and following Service Objects + CQRS principles.
+A fully open-source, self-hosted error dashboard for solo founders, indie hackers, and small teams who want complete control without the SaaS bills.
-**Tested on**: Rails 7.0, 7.1, 7.2, 8.0 | Ruby 3.2, 3.3+
+```ruby
+gem 'rails_error_dashboard'
+```
-![Dashboard Screenshot](https://via.placeholder.com/800x400?text=Error+Dashboard+Screenshot)
+**5-minute setup** · **Works out-of-the-box** · **100% Rails + Postgres** · **No vendor lock-in**
-## 📖 Table of Contents
-- [Features](#-features)
-- [Installation](#-installation)
-- [Configuration](#️-configuration)
-- [Usage](#-usage)
-  - [Automatic Error Tracking](#automatic-error-tracking)
-  - [Manual Error Logging](#manual-error-logging)
-  - [Frontend & Mobile Error Reporting](#frontend--mobile-error-reporting)
-- [Optional Separate Database](#️-optional-separate-database)
-- [Advanced Features](#-advanced-features)
-  - [Notification System](#-notification-system)
-  - [Platform Detection](#platform-detection)
-- [Architecture Details](#-architecture-details)
-- [Documentation](#-documentation)
-- [Contributing](#-contributing)
-- [License](#-license)
+---
-## ✨ Features
+### ⚠️ BETA SOFTWARE
+This Rails Engine is in beta and under active development. While functional and tested (850+ tests passing), the API may change before v1.0.0. Use in production at your own discretion.
-### 🎯 Complete Error Tracking
-- **Automatic error capture** from Rails controllers, jobs, services, and middleware
-- **Frontend & mobile support** - React, React Native, Vue, Angular, Flutter, and more
-- **Platform detection** (iOS/Android/Web/API) using user agent parsing
-- **User context tracking** with optional user associations
-- **Request context** including URL, params, IP address, component/screen
-- **Full stack traces** for debugging (Ruby + JavaScript)
-### 📊 Beautiful Dashboard
-- **Modern UI** with Bootstrap 5
-- **Dark/Light mode** with theme switcher
-- **Responsive design** for mobile and desktop
-- **Real-time statistics** and error counts
-- **Search and filtering** by type, platform, environment
-- **Fast pagination** with Pagy (40x faster than Kaminari)
-### 📈 Analytics & Insights
-- **Time-series charts** showing error trends
-- **Breakdown by type**, platform, and environment
-- **Resolution rate tracking**
-- **Top affected users**
-- **Mobile vs API analysis**
-- **Customizable date ranges** (7, 14, 30, 90 days)
-### ✅ Resolution Tracking
-- Mark errors as resolved
-- Add resolution comments
-- Link to PRs, commits, or issues
-- Track resolver name and timestamp
-- View related errors
-- **Batch operations** - resolve or delete multiple errors at once
-### 🚨 Multi-Channel Alerting
-- **5 notification backends**: Email, Slack, Discord, PagerDuty, Webhooks
-- **Slack notifications** with beautifully formatted messages
-- **Discord notifications** with rich embeds and color-coded severity
-- **PagerDuty integration** for critical errors (on-call escalation)
-- **Custom webhooks** for integration with any monitoring service
-- **Email alerts** with HTML templates to multiple recipients
-- **Instant notifications** when errors occur (async background jobs)
-- **Rich context** including user, platform, environment, stack trace
-- **Direct links** to view full error details in dashboard
-- **Customizable** - enable/disable channels independently
-See [NOTIFICATION_CONFIGURATION.md](NOTIFICATION_CONFIGURATION.md) for detailed setup.
-### 🔒 Security & Configuration
-- **HTTP Basic Auth** (configurable)
-- **Environment-based settings**
-- **Optional separate database** for performance isolation
-### 🔌 Plugin System
-- **Extensible architecture** for custom integrations
-- **Event hooks** throughout error lifecycle
-- **Built-in examples**: Metrics tracking, Audit logging, Jira integration
-- **Easy to create** custom plugins for any service
-- **Safe execution** - plugin errors don't break the app
-Common plugin use cases:
-- 📊 Send metrics to StatsD, Datadog, Prometheus
-- 🎫 Create tickets in Jira, Linear, GitHub Issues
-- 📝 Log audit trails for compliance
-- 📢 Send custom notifications
-- 💾 Archive errors to data warehouses
-See [PLUGIN_SYSTEM_GUIDE.md](PLUGIN_SYSTEM_GUIDE.md) for detailed documentation.
-### 🏗️ Architecture
-Built with **Service Objects + CQRS Principles**:
-- **Commands**: LogError, ResolveError, BatchResolveErrors, BatchDeleteErrors (write operations)
-- **Queries**: ErrorsList, DashboardStats, AnalyticsStats (read operations)
-- **Value Objects**: ErrorContext (immutable data)
-- **Services**: PlatformDetector (business logic)
-- **Plugins**: Extensible event-driven architecture
-### ✅ Multi-Version Testing
-- **Rails Support**: 7.0, 7.1, 7.2, 8.0
-- **Ruby Support**: 3.2, 3.3+
-- **CI/CD**: 8 version combinations tested automatically
-- **Compatibility**: 100% feature parity across all versions
-See [MULTI_VERSION_TESTING.md](MULTI_VERSION_TESTING.md) for testing guide.
-## 🧪 Implementation Status
-### ✅ Phase 1: Core Error Tracking (COMPLETE & TESTED)
-- Error logging and deduplication
-- Automatic tracking via middleware
-- Controller/action context
-- Request metadata capture
-- User tracking
-- Dashboard UI with search/filter
-- Stack trace viewer
-- Mark errors as resolved
-- **Test Coverage**: 111 RSpec examples passing
-### ✅ Phase 2: Multi-Channel Notifications (COMPLETE)
-- Slack integration
-- Email notifications
-- Discord webhooks
-- PagerDuty integration
-- Custom webhooks
-- **Test Coverage**: Needs additional tests (functional but not extensively tested)
-### ✅ Phase 3: Batch Operations (COMPLETE)
-- Bulk resolve errors
-- Bulk delete errors
-- API endpoints
-- **Test Coverage**: Needs additional tests (functional but not extensively tested)
-### ✅ Phase 4: Analytics & Insights (COMPLETE)
-- Error trends over time
-- Platform breakdown
-- Developer insights
-- Dashboard statistics
-- **Test Coverage**: Needs additional tests (functional but not extensively tested)
-### ✅ Phase 5: Plugin System (COMPLETE)
-- Plugin architecture
-- Event hooks
-- Built-in plugins (Jira, Metrics, Audit Log)
-- **Test Coverage**: Needs additional tests (functional but not extensively tested)
-### 🔜 What's Next
-- Expand test coverage for Phases 2-5
-- Real-world production testing
-- Performance optimizations
-- Additional integrations based on feedback
-## 📦 Installation
+**Supports**: Rails 7.0 - 8.1 | Ruby 3.2+
-### 1. Add to Gemfile
+---
-```ruby
-gem 'rails_error_dashboard'
-```
+## 🎯 Who This Is For
-### 2. Install the gem
+✓ **Solo bootstrappers** who need professional error tracking without recurring costs
-```bash
-bundle install
-```
+✓ **Indie SaaS founders** building profitable apps on tight budgets
-### 3. Run the installer
+✓ **Small dev teams** (2-5 people) who hate SaaS bloat
-```bash
-rails generate rails_error_dashboard:install
-```
+✓ **Privacy-conscious apps** that need to keep error data on their own servers
-This will:
-- Create `config/initializers/rails_error_dashboard.rb`
-- Copy migrations to your app
-- Mount the engine at `/error_dashboard`
+✓ **Side projects** that might become real businesses
-### 4. Run migrations
+---
-```bash
-rails db:migrate
-```
+## 💰 What It Replaces
-### 5. (Optional) Configure queue for notifications
+| Before | After |
+|--------|-------|
+| Pay $29-99/month for error monitoring | $0/month - runs on your existing Rails server |
+| Send sensitive error data to third parties | Keep all data on your infrastructure |
+| Fight with SaaS pricing tiers and limits | Unlimited errors, unlimited projects |
+| Vendor lock-in with proprietary APIs | 100% open source, fully portable |
+| Complex setup with SDKs and external services | 5-minute Rails Engine installation |
-If you're using **Sidekiq**, add the notification queue to your config:
+---
-```yaml
-# config/sidekiq.yml
-:queues:
-  - error_notifications
-  - default
-  - mailers
-```
+## 🚀 Why Choose Rails Error Dashboard
-If you're using **Solid Queue** (Rails 8.1+), add to your config:
-```yaml
-# config/queue.yml
-workers:
-  - queues: error_notifications
-    threads: 3
-    processes: 1
-  - queues: default
-    threads: 5
-    processes: 1
-```
+**"Install once, own it forever"**
-**Note:** If you're using the default `async` adapter or other backends, no additional configuration is needed. The gem works with all ActiveJob adapters out of the box.
+- ✅ **Zero recurring costs** - One-time setup, runs on your existing infrastructure
+- ✅ **5-minute installation** - Mount the Rails Engine, run migrations, done
+- ✅ **Works immediately** - Automatic error capture from Rails controllers, jobs, models
+- ✅ **Beautiful UI** - Professional dashboard you can show to clients
+- ✅ **Full control** - Your data stays on your server, modify anything you want
+- ✅ **No surprises** - Open source MIT license, no hidden fees or limits
-### 6. Visit the dashboard
+**Built for developers who:**
+- Want professional error monitoring without the SaaS tax
+- Need to debug production issues without paying per error
+- Value data privacy and server ownership
+- Prefer simple, Rails-native solutions
-Start your server and visit:
-```
-http://localhost:3000/error_dashboard
-```
+---
-**Default credentials** (change in the initializer):
-- Username: `admin`
-- Password: `password`
+![Dashboard Screenshot](https://via.placeholder.com/800x400?text=Error+Dashboard+Screenshot)
-## ⚙️ Configuration
+---
-Edit `config/initializers/rails_error_dashboard.rb`:
+## ✨ Features
-```ruby
-RailsErrorDashboard.configure do |config|
-  # Dashboard authentication
-  config.dashboard_username = ENV.fetch('ERROR_DASHBOARD_USER', 'admin')
-  config.dashboard_password = ENV.fetch('ERROR_DASHBOARD_PASSWORD', 'password')
-  config.require_authentication = true
-  config.require_authentication_in_development = false
+### Core Features (Always Enabled)
-  # User model for associations
-  config.user_model = 'User'
+#### 🎯 Complete Error Tracking
+Automatic error capture from Rails controllers, jobs, and middleware. Frontend & mobile support for React, React Native, Vue, Angular, Flutter. Platform detection (iOS/Android/Web/API), user context tracking, full stack traces.
-  # === Notification Settings ===
+#### 📊 Beautiful Dashboard
+Modern Bootstrap 5 UI with dark/light mode, responsive design, real-time statistics, search and filtering, fast pagination. Overview dashboard with critical alerts, error trend charts, and platform health summary.
-  # Slack notifications
-  config.enable_slack_notifications = true
-  config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']
+#### 📈 Analytics & Insights
+7-day trend charts, severity breakdown, spike detection, resolution rate tracking, user impact analysis. Comprehensive analytics page with hourly patterns, mobile vs API breakdowns, and top affected users.
-  # Email notifications
-  config.enable_email_notifications = true
-  config.notification_email_recipients = ENV.fetch('ERROR_NOTIFICATION_EMAILS', '').split(',').map(&:strip)
-  config.notification_email_from = ENV.fetch('ERROR_NOTIFICATION_FROM', 'errors@example.com')
+#### 🔧 Workflow Management
+Error assignment and status tracking, priority levels (critical/high/medium/low), snooze functionality, comment threads, batch operations (bulk resolve/delete), resolution tracking with references.
-  # Dashboard base URL (for notification links)
-  config.dashboard_base_url = ENV['DASHBOARD_BASE_URL']
+#### 🔒 Security & Privacy
+HTTP Basic Auth, environment-based settings, optional separate database for isolation. Your data stays on your server - no third-party access.
-  # Separate database (optional - for high-volume apps)
-  config.use_separate_database = ENV.fetch('USE_SEPARATE_ERROR_DB', 'false') == 'true'
+### Optional Features (Choose During Install)
-  # Retention policy
-  config.retention_days = 90
+#### 🚨 Multi-Channel Notifications
-  # Error catching
-  config.enable_middleware = true
-  config.enable_error_subscriber = true
-end
-```
+- **Slack** - Rich formatted messages with error context and direct dashboard links
+- **Email** - HTML formatted alerts with full error details
+- **Discord** - Embedded messages with severity color coding
+- **PagerDuty** - Critical error escalation with incident management
+- **Webhooks** - Custom integrations with any service (JSON payloads)
-### Environment Variables
+#### ⚡ Performance Optimizations
-```bash
-# .env
-ERROR_DASHBOARD_USER=admin
-ERROR_DASHBOARD_PASSWORD=your_secure_password
+- **Async Logging** - Non-blocking error capture using ActiveJob (Sidekiq/SolidQueue/Async)
+- **Error Sampling** - Reduce storage by sampling high-frequency errors
+- **Backtrace Limiting** - Save 70-90% storage with smart truncation
+- **Separate Database** - Isolate error data for better performance
+- **Database Indexes** - Composite indexes and PostgreSQL GIN full-text search
-# Slack notifications
-SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
+#### 🧠 Advanced Analytics (8 Powerful Features)
-# Email notifications (comma-separated list)
-ERROR_NOTIFICATION_EMAILS=dev-team@example.com,ops@example.com
-ERROR_NOTIFICATION_FROM=errors@myapp.com
+**1. Baseline Anomaly Alerts** 🔔
+Automatically detect unusual error rate spikes using statistical analysis (mean + std dev). Get proactive notifications when errors exceed expected baselines with intelligent cooldown to avoid alert fatigue.
-# Dashboard URL (used in notification links)
-DASHBOARD_BASE_URL=https://myapp.com
+**2. Fuzzy Error Matching** 🔍
+Find similar errors across different error hashes using Jaccard similarity (70%) and Levenshtein distance (30%). Discover related errors that share common root causes even when they manifest differently.
-USE_SEPARATE_ERROR_DB=false  # Set to true for separate database
-```
+**3. Co-occurring Errors** 🔗
+Detect errors that happen together within configurable time windows (default: 5 minutes). Identify patterns where one error frequently triggers another, helping you prioritize fixes.
-## 🚀 Usage
+**4. Error Cascade Detection** ⛓️
+Identify error chains (A causes B causes C) with probability calculations and average delays. Visualize parent→child relationships to understand cascading failures and fix root causes.
-### Automatic Error Tracking
+**5. Error Correlation Analysis** 📊
+Correlate errors with app versions, git commits, and users. Find problematic releases, identify users affected by multiple error types, and detect time-based patterns.
-The gem automatically tracks errors from:
-- **Controllers** (via Rails error reporting)
-- **Background jobs** (ActiveJob, Sidekiq)
-- **Rack middleware** (catches everything else)
+**6. Platform Comparison** 📱
+Compare iOS vs Android vs Web health metrics side-by-side. Platform-specific error rates, severity distributions, resolution times, and stability scores (0-100).
-No code changes needed! Just install and go.
+**7. Occurrence Pattern Detection** 📈
+Detect cyclical patterns (business hours, nighttime, weekend rhythms) and error bursts (many errors in short time). Understand when and how your errors happen.
-### Manual Error Logging
+**8. Developer Insights** 💡
+AI-powered insights with severity detection, platform stability scoring, actionable recommendations, and recent error activity summaries.
+#### 🔌 Plugin System
+Extensible architecture with event hooks (`on_error_logged`, `on_error_resolved`, `on_threshold_exceeded`). Built-in examples for Jira integration, metrics tracking, audit logging. Easy to create custom plugins - just drop a file in `config/initializers/error_dashboard_plugins/`.
+**📚 [View complete feature list with examples →](docs/FEATURES.md)**
+---
-You can also manually log errors:
+## 📦 Quick Start
+### 1. Add to Gemfile
 ```ruby
-begin
-  # Your code
-rescue => e
-  Rails.error.report(e,
-    handled: true,
-    severity: :error,
-    context: {
-      current_user: current_user,
-      custom_data: "anything you want"
-    }
-  )
-end
+gem 'rails_error_dashboard'
 ```
-### Frontend & Mobile Error Reporting
+### 2. Install with Interactive Setup
+```bash
+bundle install
+rails generate rails_error_dashboard:install
+rails db:migrate
+```
-Rails Error Dashboard can track errors from **any frontend or mobile application** - not just your Rails backend!
+The installer will guide you through optional feature selection:
+- **Notifications** (Slack, Email, Discord, PagerDuty, Webhooks)
+- **Performance** (Async Logging, Error Sampling, Separate Database)
+- **Advanced Analytics** (8 powerful features including baseline alerts, fuzzy matching, platform comparison)
-**Supported platforms:**
-- 📱 **React Native** (iOS & Android)
-- ⚛️ **React** (Web)
-- 🅰️ **Angular**
-- 💚 **Vue.js**
-- 📱 **Flutter** (via HTTP)
-- 📱 **Swift/Kotlin** (Native apps)
-- 🌐 **Any JavaScript/TypeScript** application
+**All features are opt-in** - choose what you need during installation, or enable/disable them later in the initializer.
-#### Quick Setup
+This will:
+- Create `config/initializers/rails_error_dashboard.rb` with your selected features
+- Copy database migrations
+- Mount the engine at `/error_dashboard`
-**1. Create an API endpoint in your Rails app:**
+### 3. Visit your dashboard
-```ruby
-# app/controllers/api/v1/mobile_errors_controller.rb
-module Api
-  module V1
-    class MobileErrorsController < BaseController
-      def create
-        mobile_error = MobileError.new(error_params)
-        RailsErrorDashboard::Commands::LogError.call(
-          mobile_error,
-          {
-            current_user: current_user,
-            request: request,
-            source: :mobile_app  # or :react, :vue, :angular, etc.
-          }
-        )
-        render json: { success: true }, status: :created
-      end
-      private
-      def error_params
-        params.require(:error).permit(:error_type, :message, :stack, :component)
-      end
-      class MobileError < StandardError
-        attr_reader :mobile_data
-        def initialize(data)
-          @mobile_data = data
-          super(data[:message])
-        end
-        def backtrace
-          @mobile_data[:stack]&.split("\n") || []
-        end
-      end
-    end
-  end
-end
+Start your server and visit:
+```
+http://localhost:3000/error_dashboard
 ```
-**2. Report errors from your frontend:**
+**Default credentials:**
+- Username: `gandalf`
+- Password: `youshallnotpass`
-```javascript
-// React/React Native/Vue/Angular
-async function reportError(error, component) {
-  try {
-    await fetch('/api/v1/mobile_errors', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${authToken}`
-      },
-      body: JSON.stringify({
-        error: {
-          error_type: error.name,
-          message: error.message,
-          stack: error.stack,
-          component: component
-        }
-      })
-    });
-  } catch (e) {
-    console.error('Failed to report error:', e);
-  }
-}
+⚠️ **Change these before production!** Edit `config/initializers/rails_error_dashboard.rb`
-// Usage in React component
-try {
-  // Your code
-} catch (error) {
-  reportError(error, 'UserProfile');
-  // Handle error in UI
-}
+### 4. Test it out
+Trigger a test error to see it in action:
+```ruby
+# In Rails console or any controller
+raise "Test error from Rails Error Dashboard!"
 ```
-**3. Add Error Boundary (React/React Native):**
+The error will appear instantly in your dashboard with full context, backtrace, and platform information.
-```jsx
-class ErrorBoundary extends React.Component {
-  componentDidCatch(error, errorInfo) {
-    reportError(error, errorInfo.componentStack);
-  }
+**📘 [Full installation guide →](docs/QUICKSTART.md)**
-  render() {
-    return this.props.children;
-  }
-}
-```
+---
-**Benefits:**
-- ✅ **Single dashboard** for all errors (backend + frontend + mobile)
-- ✅ **Platform detection** - errors automatically tagged by source
-- ✅ **User tracking** - errors associated with logged-in users
-- ✅ **Real-time notifications** - Slack/Email alerts for frontend errors too
-- ✅ **Component tracking** - know which component/screen errored
-- ✅ **Stack traces** - full JavaScript stack traces
+## ⚙️ Configuration
-**📚 Complete Integration Guide:**
+### Opt-in Feature System
-For detailed setup instructions including:
-- Offline support and retry logic
-- Batch error reporting
-- React Native integration
-- Error filtering and deduplication
-- Best practices
+Rails Error Dashboard uses an **opt-in architecture** - core features (error capture, dashboard UI, analytics) are always enabled, while everything else is disabled by default.
-See: [MOBILE_APP_INTEGRATION.md](MOBILE_APP_INTEGRATION.md)
+**Tier 1 Features (Always ON)**:
+- ✅ Error capture (controllers, jobs, middleware)
+- ✅ Dashboard UI with search and filtering
+- ✅ Real-time updates
+- ✅ Analytics and trend charts
-### Accessing the Dashboard
+**Optional Features (Choose During Install)**:
+- 📧 Multi-channel notifications (Slack, Email, Discord, PagerDuty, Webhooks)
+- ⚡ Performance optimizations (Async logging, Error sampling)
+- 📊 Advanced analytics (Baseline alerts, Fuzzy matching, Platform comparison, and more)
-Navigate to `/error_dashboard` to view:
-- **Overview**: Recent errors, statistics, quick filters
-- **All Errors**: Paginated list with filtering and search
-- **Analytics**: Charts, trends, and insights
-- **Error Details**: Full stack trace, context, and resolution tracking
+### Basic Configuration
-### Resolution Workflow
+Edit `config/initializers/rails_error_dashboard.rb`:
-1. Click on an error to view details
-2. Investigate the stack trace and context
-3. Fix the issue in your code
-4. Mark as resolved with:
-   - Resolution comment (what was the fix)
-   - Reference link (PR, commit, issue)
-   - Your name
+```ruby
+RailsErrorDashboard.configure do |config|
+  # ============================================================================
+  # AUTHENTICATION (Always Required)
+  # ============================================================================
+  config.dashboard_username = ENV.fetch('ERROR_DASHBOARD_USER', 'gandalf')
+  config.dashboard_password = ENV.fetch('ERROR_DASHBOARD_PASSWORD', 'youshallnotpass')
-## 🗄️ Optional Separate Database
+  # ============================================================================
+  # OPTIONAL FEATURES (Enable as needed)
+  # ============================================================================
-For high-volume applications, you can use a separate database for error logs:
+  # Slack notifications (if enabled during install)
+  config.enable_slack_notifications = true
+  config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']
-### Benefits
-- **Performance isolation** - error logging doesn't slow down main DB
-- **Independent scaling** - different hardware for different workloads
-- **Different retention policies** - auto-delete old errors
-- **Security isolation** - separate access controls
+  # Email notifications (if enabled during install)
+  config.enable_email_notifications = true
+  config.notification_email_recipients = ["dev@yourapp.com"]
+  config.notification_email_from = "errors@yourapp.com"
-### Setup
+  # Async logging for better performance (if enabled during install)
+  config.async_logging = true
+  config.async_adapter = :sidekiq  # or :solid_queue, :async
-1. **Enable in config**:
-```ruby
-config.use_separate_database = true
+  # Advanced analytics features (if enabled during install)
+  config.enable_baseline_alerts = true
+  config.enable_similar_errors = true
+  config.enable_platform_comparison = true
+end
 ```
-2. **Configure database.yml**:
-```yaml
-production:
-  primary:
-    database: myapp_production
-    # ... your main DB config
-  error_logs:
-    database: myapp_error_logs_production
-    username: <%= ENV['ERROR_LOGS_DATABASE_USER'] %>
-    password: <%= ENV['ERROR_LOGS_DATABASE_PASSWORD'] %>
-    migrations_paths: db/error_logs_migrate
-```
+All features can be toggled on/off at any time by editing the initializer.
+### Environment Variables
-3. **Create and migrate**:
 ```bash
-rails db:create:error_logs
-rails db:migrate:error_logs
+# .env
+ERROR_DASHBOARD_USER=your_username
+ERROR_DASHBOARD_PASSWORD=your_secure_password
+SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
+DASHBOARD_BASE_URL=https://yourapp.com
 ```
-### Migrating Existing Data
-If you already have error logs in your primary database and want to move them to the separate database:
+**📖 [Complete configuration guide →](docs/guides/CONFIGURATION.md)**
-**📚 Complete Migration Guide:** See [MIGRATION_TO_SEPARATE_DATABASE.md](MIGRATION_TO_SEPARATE_DATABASE.md)
+---
-The guide covers:
-- Step-by-step migration process
-- Data integrity verification
-- Safe cleanup of old data
-- Rollback procedures
-- Performance considerations
-- Troubleshooting common issues
+## 🚀 Usage
-**Quick summary:**
-```bash
-# 1. Configure separate database in database.yml
-# 2. Create the new database
-rails db:create:error_logs
-rails db:migrate:error_logs
+### Automatic Error Tracking
-# 3. Copy data (use rake task from migration guide)
-rake error_logs:migrate_to_separate_db
+Rails Error Dashboard automatically tracks errors from:
+- **Controllers** (via Rails error reporting)
+- **Background jobs** (ActiveJob, Sidekiq)
+- **Rack middleware** (catches everything else)
-# 4. Verify migration
-rake error_logs:verify_migration
+No additional code needed! Just install and it works.
-# 5. Enable in config and restart app
-# 6. Clean up primary database
-rake error_logs:cleanup_primary_db
-```
+### Manual Error Logging
-## 🔧 Advanced Features
-### 📧 Notification System
-Rails Error Dashboard includes a powerful multi-channel notification system to alert your team when errors occur.
-#### Slack Notifications
-Get instant alerts in Slack with rich, formatted messages including:
-- Error type and message
-- Environment (Production, Staging, etc.)
-- Platform (iOS, Android, API)
-- User information
-- Request details
-- Direct link to view full error in dashboard
-**Setup:**
-1. Create a Slack webhook URL:
-   - Go to https://api.slack.com/messaging/webhooks
-   - Create a new webhook for your channel
-   - Copy the webhook URL
-2. Configure in your app:
-   ```bash
-   # .env
-   SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
-   DASHBOARD_BASE_URL=https://myapp.com
-   ```
-3. Enable in initializer (enabled by default):
-   ```ruby
-   config.enable_slack_notifications = true
-   config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']
-   ```
-**Slack Message Features:**
-- 🎨 Beautifully formatted with color-coded blocks
-- 📱 Platform emoji indicators (iOS 📱, Android 🤖, API 🔌)
-- 👤 User and IP address tracking
-- 🔗 Direct "View Details" button linking to dashboard
-- ⏰ Timestamp with timezone
-#### Email Notifications
-Send detailed email alerts to your team with HTML and plain text versions.
-**Email Features:**
-- 📨 Beautiful HTML email template with your app's branding
-- 📄 Plain text fallback for email clients
-- 🎯 Send to multiple recipients
-- 📊 Full error context including stack trace
-- 🔗 One-click link to view in dashboard
-- 🏷️ Environment and platform badges
-**Setup:**
-1. Configure recipients and sender:
-   ```bash
-   # .env
-   ERROR_NOTIFICATION_EMAILS=dev-team@example.com,ops@example.com,alerts@example.com
-   ERROR_NOTIFICATION_FROM=errors@myapp.com
-   DASHBOARD_BASE_URL=https://myapp.com
-   ```
-2. Enable in initializer (enabled by default):
-   ```ruby
-   config.enable_email_notifications = true
-   config.notification_email_recipients = ENV.fetch('ERROR_NOTIFICATION_EMAILS', '').split(',').map(&:strip)
-   config.notification_email_from = ENV.fetch('ERROR_NOTIFICATION_FROM', 'errors@example.com')
-   ```
-3. Ensure your Rails app has ActionMailer configured:
-   ```ruby
-   # config/environments/production.rb
-   config.action_mailer.delivery_method = :smtp
-   config.action_mailer.smtp_settings = {
-     address: 'smtp.sendgrid.net',
-     port: 587,
-     domain: 'myapp.com',
-     user_name: ENV['SENDGRID_USERNAME'],
-     password: ENV['SENDGRID_PASSWORD'],
-     authentication: 'plain',
-     enable_starttls_auto: true
-   }
-   ```
-**Email Template Includes:**
-- Error type and full message
-- Environment badge (Production/Staging/Development)
-- Platform badge (iOS/Android/API)
-- Timestamp with timezone
-- User email and IP address
-- Request URL and parameters
-- First 10 lines of stack trace
-- Prominent "View Full Details" button
-#### Disabling Notifications
-You can selectively disable notifications:
+For frontend/mobile apps or custom error logging:
 ```ruby
-# Disable Slack only
-config.enable_slack_notifications = false
-# Disable email only
-config.enable_email_notifications = false
-# Disable both
-config.enable_slack_notifications = false
-config.enable_email_notifications = false
+# From your Rails API
+RailsErrorDashboard::Commands::LogError.call(
+  error_type: "TypeError",
+  message: "Cannot read property 'name' of null",
+  backtrace: ["App.js:42", "index.js:12"],
+  platform: "iOS",
+  app_version: "2.1.0",
+  user_id: current_user.id,
+  context: {
+    component: "ProfileScreen",
+    device_model: "iPhone 14 Pro"
+  }
+)
 ```
-#### Notification Workflow
+### Frontend Integration
-When an error occurs:
-1. Error is logged to database
-2. Notifications are sent **asynchronously** via background jobs
-3. Your team receives alerts via configured channels
-4. Team clicks link in notification to view full details
-5. Error can be investigated and marked as resolved in dashboard
+```javascript
+// React Native example
+try {
+  // Your code
+} catch (error) {
+  fetch('https://yourapp.com/api/errors', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      error_type: error.name,
+      message: error.message,
+      backtrace: error.stack.split('\n'),
+      platform: Platform.OS, // 'ios' or 'android'
+      app_version: VERSION
+    })
+  });
+}
+```
-#### Queue Configuration
+**📱 [Mobile app integration guide →](docs/guides/MOBILE_APP_INTEGRATION.md)**
-Notification jobs use the `:error_notifications` queue by default. This allows you to:
-- Prioritize error notifications over other jobs
-- Monitor notification delivery separately
-- Configure different concurrency/workers for notifications
+---
-**Works with all ActiveJob backends:**
-- ✅ **Solid Queue** (Rails 8.1+ default)
-- ✅ **Sidekiq** (most popular)
-- ✅ **Delayed Job**
-- ✅ **Resque**
-- ✅ **Async** (Rails default for development)
-- ✅ **Inline** (for testing)
+## 🔔 Notifications
-**Setup for Sidekiq:**
+Set up multi-channel notifications in minutes:
+### Slack
 ```ruby
-# config/sidekiq.yml
-:queues:
-  - default
-  - error_notifications  # Add this queue
-  - mailers
-# Optional: Higher priority for error notifications
-:queues:
-  - [error_notifications, 5]  # Process 5x more often
-  - [default, 1]
-  - [mailers, 1]
+config.enable_slack_notifications = true
+config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']
 ```
-**Setup for Solid Queue (Rails 8.1+):**
+### Discord
 ```ruby
-# config/queue.yml
-dispatchers:
-  batch_size: 500
-workers:
-  - queues: error_notifications
-    threads: 3
-    processes: 1
-    polling_interval: 1
-  - queues: default
-    threads: 5
-    processes: 1
-    polling_interval: 5
+config.enable_discord_notifications = true
+config.discord_webhook_url = ENV['DISCORD_WEBHOOK_URL']
 ```
-**No additional setup needed for:**
-- Async adapter (Rails default in development)
-- Inline adapter (synchronous, for testing)
-- Other adapters use the queue name automatically
-**Background Jobs:**
-- Notifications use `ActiveJob` and run in background
-- Use dedicated `:error_notifications` queue
-- Won't block or slow down your application
-- Failed notifications are logged but don't raise errors
-- Retries handled by your ActiveJob backend (Sidekiq, Solid Queue, etc.)
-### Platform Detection
-Automatically detects:
-- **iOS** - iPhone, iPad apps
-- **Android** - Android apps
-- **API** - Backend services, web requests
-### User Association
+### PagerDuty (Critical Errors Only)
+```ruby
+config.enable_pagerduty_notifications = true
+config.pagerduty_integration_key = ENV['PAGERDUTY_INTEGRATION_KEY']
+```
-Errors are automatically associated with the current user (if signed in). Configure the user model name if it's not `User`.
+### Custom Webhooks
+```ruby
+config.enable_webhook_notifications = true
+config.webhook_urls = ['https://yourapp.com/hooks/errors']
+```
-### Retention Policy
+**🔕 [Notification setup guide →](docs/guides/NOTIFICATIONS.md)**
-Old errors are automatically cleaned up based on `retention_days` configuration.
+---
-## 📊 Architecture Details
+## 📚 Documentation
-### Service Objects Pattern
+### Getting Started
+- **[Quickstart Guide](docs/QUICKSTART.md)** - Complete 5-minute setup
+- **[Configuration](docs/guides/CONFIGURATION.md)** - All configuration options
+- **[Mobile App Integration](docs/guides/MOBILE_APP_INTEGRATION.md)** - React Native, Flutter, etc.
-**Commands** (Write Operations):
-```ruby
-# Create an error log
-RailsErrorDashboard::Commands::LogError.call(exception, context)
+### Features
+- **[Complete Feature List](docs/FEATURES.md)** - Every feature explained
+- **[Notifications](docs/guides/NOTIFICATIONS.md)** - Multi-channel alerting
+- **[Batch Operations](docs/guides/BATCH_OPERATIONS.md)** - Bulk resolve/delete
+- **[Real-Time Updates](docs/guides/REAL_TIME_UPDATES.md)** - Live dashboard
+- **[Error Trend Visualizations](docs/guides/ERROR_TREND_VISUALIZATIONS.md)** - Charts & analytics
-# Mark error as resolved
-RailsErrorDashboard::Commands::ResolveError.call(error_id, resolution_data)
-```
+### Advanced
+- **[Plugin System](docs/PLUGIN_SYSTEM.md)** - Build custom integrations
+- **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation
+- **[Customization Guide](docs/CUSTOMIZATION.md)** - Customize everything
+- **[Database Options](docs/guides/DATABASE_OPTIONS.md)** - Separate database setup
+- **[Database Optimization](docs/guides/DATABASE_OPTIMIZATION.md)** - Performance tuning
-**Queries** (Read Operations):
-```ruby
-# Get filtered errors
-RailsErrorDashboard::Queries::ErrorsList.call(filters)
+### Development
+- **[Testing](docs/development/TESTING.md)** - Multi-version testing
-# Get dashboard stats
-RailsErrorDashboard::Queries::DashboardStats.call
+**📖 [View all documentation →](docs/README.md)**
-# Get analytics
-RailsErrorDashboard::Queries::AnalyticsStats.call(days: 30)
-```
+---
-### Database Schema
+## 🏗️ Architecture
-```ruby
-create_table :rails_error_dashboard_error_logs do |t|
-  # Error details
-  t.string :error_type, null: false
-  t.text :message, null: false
-  t.text :backtrace
-  # Context
-  t.integer :user_id
-  t.text :request_url
-  t.text :request_params
-  t.text :user_agent
-  t.string :ip_address
-  t.string :environment, null: false
-  t.string :platform
-  # Resolution tracking
-  t.boolean :resolved, default: false
-  t.text :resolution_comment
-  t.string :resolution_reference
-  t.string :resolved_by_name
-  t.datetime :resolved_at
-  # Timestamps
-  t.datetime :occurred_at, null: false
-  t.timestamps
-end
-```
+Built with **Service Objects + CQRS Principles**:
+- **Commands**: LogError, ResolveError, BatchOperations (write operations)
+- **Queries**: ErrorsList, DashboardStats, Analytics (read operations)
+- **Value Objects**: ErrorContext (immutable data)
+- **Services**: PlatformDetector, SimilarityCalculator (business logic)
+- **Plugins**: Event-driven extensibility
-## 📚 Documentation
+Clean, maintainable, testable architecture you can understand and modify.
-### User Guides
-- **[README.md](README.md)** - Main documentation (you are here!)
-- **[NOTIFICATION_CONFIGURATION.md](NOTIFICATION_CONFIGURATION.md)** - Multi-channel notifications setup (Slack, Email, Discord, PagerDuty, Webhooks)
-- **[MOBILE_APP_INTEGRATION.md](MOBILE_APP_INTEGRATION.md)** - Complete guide for integrating with React Native, Expo, and other mobile frameworks
-- **[BATCH_OPERATIONS_GUIDE.md](BATCH_OPERATIONS_GUIDE.md)** - Bulk resolve/delete errors guide
-- **[PLUGIN_DEVELOPMENT_GUIDE.md](PLUGIN_DEVELOPMENT_GUIDE.md)** - Create custom plugins for Jira, metrics, etc.
-### Operations & Deployment
-- **[MIGRATION_TO_SEPARATE_DATABASE.md](MIGRATION_TO_SEPARATE_DATABASE.md)** - Step-by-step guide for migrating to a separate error logs database
-- **[MULTI_VERSION_TESTING.md](MULTI_VERSION_TESTING.md)** - Testing across Rails 7.0-8.0 and Ruby 3.2-3.3
-- **[CI_TROUBLESHOOTING.md](CI_TROUBLESHOOTING.md)** - Complete guide to CI issues and solutions (for contributors)
-### Topics Covered
-- ✅ Rails backend error tracking (automatic + manual)
-- ✅ Frontend/mobile error reporting (React, React Native, Vue, Angular, Flutter)
-- ✅ Multi-channel notifications (Slack, Email, Discord, PagerDuty, Webhooks)
-- ✅ Analytics and dashboard usage
-- ✅ Separate database setup and migration
-- ✅ Queue configuration (Sidekiq, Solid Queue, etc.)
-- ✅ Plugin system and custom integrations
-- ✅ Batch operations (bulk resolve/delete)
-- ✅ Multi-version compatibility (Rails 7.0-8.0, Ruby 3.2-3.3)
-- ✅ Security and authentication
-- ✅ Service Objects + CQRS architecture
+---
 ## 🤝 Contributing
-Contributions are welcome! Please:
+We welcome contributions! Here's how to get started:
 1. Fork the repository
-2. Create a 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
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Write tests for your changes
+4. Ensure all tests pass (`bundle exec rspec`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
 ### Development Setup
 ```bash
 git clone https://github.com/AnjanJ/rails_error_dashboard.git
 cd rails_error_dashboard
+# Automated setup (installs deps, hooks, runs tests)
+bin/setup
+# Or manual setup
 bundle install
+bundle exec lefthook install  # Installs git hooks
+bundle exec rspec
 ```
+**Git Hooks:** We use [Lefthook](https://github.com/evilmartians/lefthook) to run quality checks before commit/push. This ensures CI passes and saves GitHub Actions minutes!
+**🔧 [Development guide →](DEVELOPMENT.md)** | **🧪 [Testing guide →](docs/development/TESTING.md)**
+---
 ## 📝 License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Rails Error Dashboard is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+---
 ## 🙏 Acknowledgments
@@ -845,14 +443,18 @@ The gem is available as open source under the terms of the [MIT License](https:/
 - UI powered by [Bootstrap 5](https://getbootstrap.com/)
 - Charts by [Chart.js](https://www.chartjs.org/)
 - Pagination by [Pagy](https://github.com/ddnexus/pagy)
-- Platform detection by [Browser](https://github.com/fnando/browser)
+- Platform detection by [Browser gem](https://github.com/fnando/browser)
-## 📮 Support
+---
-- **Issues**: [GitHub Issues](https://github.com/AnjanJ/rails_error_dashboard/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/AnjanJ/rails_error_dashboard/discussions)
-- **Repository**: [https://github.com/AnjanJ/rails_error_dashboard](https://github.com/AnjanJ/rails_error_dashboard)
+## 💬 Support
+- **📖 Documentation**: [docs/](docs/README.md)
+- **🐛 Issues**: [GitHub Issues](https://github.com/AnjanJ/rails_error_dashboard/issues)
+- **💡 Discussions**: [GitHub Discussions](https://github.com/AnjanJ/rails_error_dashboard/discussions)
 ---
 **Made with ❤️ by Anjan for the Rails community**
+*One Gem to rule them all, One Gem to find them, One Gem to bring them all, and in the dashboard bind them.* 🧙‍♂️