rails_event_viewer 0.1.0

data/app/views/rails_event_viewer/groups/index.html.erb

@@ -0,0 +1,115 @@
+<% content_for(:title, "Groups - Rails Event Viewer") %>
+
+<div class="space-y-6">
+  <div class="flex justify-between items-center">
+    <div>
+      <h1 class="text-2xl font-bold text-gray-900">Event Groups</h1>
+      <p class="mt-1 text-sm text-gray-500">
+        Track related events grouped by context or tags
+      </p>
+    </div>
+  </div>
+
+  <div class="bg-white rounded-lg shadow p-4">
+    <%= form_with url: rails_event_viewer.groups_path, method: :get, class: "flex items-center space-x-4" do |f| %>
+      <div class="flex items-center space-x-2">
+        <%= f.label :key, "Group by:", class: "text-sm font-medium text-gray-700" %>
+        <%= f.select :key,
+            options_for_select(@group_keys.map { |k| [k.to_s.titleize, k] }, @selected_key),
+            {},
+            class: "rounded-md border border-gray-300 shadow-sm focus:border-indigo-500 focus:ring-indigo-500 py-2 px-3" %>
+      </div>
+
+      <div class="flex items-center space-x-2">
+        <%= f.label :source, "Source:", class: "text-sm font-medium text-gray-700" %>
+        <%= f.select :source,
+            options_for_select([["Context", :context], ["Tags", :tags]], @source),
+            {},
+            class: "rounded-md border border-gray-300 shadow-sm focus:border-indigo-500 focus:ring-indigo-500 py-2 px-3" %>
+      </div>
+
+      <%= f.submit "Apply",
+          class: "bg-indigo-600 text-white px-4 py-2 rounded-md font-medium hover:bg-indigo-700 cursor-pointer" %>
+    <% end %>
+  </div>
+
+  <% if @group_keys.empty? %>
+    <div class="bg-yellow-50 border border-yellow-200 rounded-lg p-4">
+      <div class="flex">
+        <svg class="h-5 w-5 text-yellow-400" fill="currentColor" viewBox="0 0 20 20" aria-hidden="true">
+          <path fill-rule="evenodd" d="M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z" clip-rule="evenodd" />
+        </svg>
+        <div class="ml-3">
+          <h3 class="text-sm font-medium text-yellow-800">No group keys configured</h3>
+          <p class="mt-1 text-sm text-yellow-700">
+            Configure group keys in your initializer:
+            <code class="bg-yellow-100 px-1 rounded">config.group_keys = [:request_id, :order_id]</code>
+          </p>
+        </div>
+      </div>
+    </div>
+  <% elsif @groups.any? %>
+    <div class="bg-white shadow rounded-lg overflow-hidden">
+      <table class="min-w-full divide-y divide-gray-200">
+        <thead class="bg-gray-50">
+          <tr>
+            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">
+              <%= @selected_key.to_s.titleize %>
+            </th>
+            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Events</th>
+            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">First Event</th>
+            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Last Event</th>
+            <th class="px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider">Duration</th>
+          </tr>
+        </thead>
+        <tbody class="bg-white divide-y divide-gray-200">
+          <% @groups.each do |group| %>
+            <% duration = group[:last_event_at] && group[:first_event_at] ? group[:last_event_at] - group[:first_event_at] : nil %>
+            <tr class="hover:bg-gray-50">
+              <td class="px-6 py-4 whitespace-nowrap">
+                <%= link_to rails_event_viewer.group_path(group[:value], key: @selected_key, source: @source),
+                    class: "text-indigo-600 hover:text-indigo-900 font-medium" do %>
+                  <code class="text-sm bg-gray-100 px-2 py-1 rounded"><%= group[:value] %></code>
+                <% end %>
+              </td>
+              <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-900">
+                <%= number_with_delimiter(group[:count]) %>
+              </td>
+              <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
+                <% if group[:first_event_at] %>
+                  <%= time_ago_with_title(group[:first_event_at]) %>
+                <% else %>
+                  -
+                <% end %>
+              </td>
+              <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
+                <% if group[:last_event_at] %>
+                  <%= time_ago_with_title(group[:last_event_at]) %>
+                <% else %>
+                  -
+                <% end %>
+              </td>
+              <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">
+                <% if duration %>
+                  <%= format_duration(duration) %>
+                <% else %>
+                  -
+                <% end %>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  <% else %>
+    <div class="bg-white rounded-lg shadow px-6 py-12 text-center text-gray-500">
+      <svg class="mx-auto h-12 w-12 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10" />
+      </svg>
+      <h3 class="mt-2 text-sm font-medium text-gray-900">No groups found</h3>
+      <p class="mt-1 text-sm text-gray-500">
+        No events with <code class="bg-gray-100 px-1 rounded"><%= @selected_key %></code> in their <%= @source %> data.
+      </p>
+    </div>
+  <% end %>
+</div>

data/app/views/rails_event_viewer/groups/show.html.erb

@@ -0,0 +1,134 @@
+<% content_for(:title, "Group: #{@value} - Rails Event Viewer") %>
+
+<div class="space-y-6">
+  <!-- Header -->
+  <div class="flex items-center justify-between">
+    <div class="flex items-center space-x-4">
+      <%= link_to rails_event_viewer.groups_path(key: @key, source: @source), class: "text-gray-400 hover:text-gray-600", aria: { label: "Back to groups" } do %>
+        <svg class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7" />
+        </svg>
+      <% end %>
+      <div>
+        <p class="text-sm text-gray-500"><%= @key.to_s.titleize %></p>
+        <h1 class="text-2xl font-bold text-gray-900">
+          <code class="bg-gray-100 px-2 py-1 rounded"><%= @value %></code>
+        </h1>
+      </div>
+    </div>
+  </div>
+
+  <!-- Stats -->
+  <div class="grid grid-cols-1 gap-5 sm:grid-cols-4">
+    <%= render "rails_event_viewer/shared/stat_card",
+        title: "Total Events",
+        value: number_with_delimiter(@total_count),
+        icon: "database" %>
+    <%= render "rails_event_viewer/shared/stat_card",
+        title: "Event Types",
+        value: @event_names.size,
+        icon: "tag" %>
+    <%= render "rails_event_viewer/shared/stat_card",
+        title: "Duration",
+        value: @duration ? format_duration(@duration) : "-",
+        icon: "clock" %>
+    <%= render "rails_event_viewer/shared/stat_card",
+        title: "Source",
+        value: @source.to_s.titleize,
+        icon: "calendar" %>
+  </div>
+
+  <!-- Timeline -->
+  <div class="bg-white shadow rounded-lg overflow-hidden">
+    <div class="px-6 py-4 border-b border-gray-200">
+      <h3 class="text-lg font-medium text-gray-900">Event Timeline</h3>
+      <% if @first_event_at && @last_event_at %>
+        <p class="text-sm text-gray-500">
+          <%= @first_event_at.strftime("%Y-%m-%d %H:%M:%S") %> to <%= @last_event_at.strftime("%Y-%m-%d %H:%M:%S") %>
+        </p>
+      <% end %>
+    </div>
+
+    <% if @events.any? %>
+      <div class="relative">
+        <div class="absolute left-12 top-0 bottom-0 w-0.5 bg-gray-200"></div>
+
+        <div class="divide-y divide-gray-100">
+          <% @events.each_with_index do |event, index| %>
+            <a href="<%= rails_event_viewer.event_path(event_id(event)) %>" class="relative pl-16 pr-6 py-4 hover:bg-gray-50 block">
+              <div class="absolute left-10 top-6 w-4 h-4 rounded-full border-2 border-indigo-500 bg-white"></div>
+
+              <% if @first_event_at && event_occurred_at(event) %>
+                <% offset = event_occurred_at(event) - @first_event_at %>
+                <div class="absolute left-0 top-4 w-9 text-right">
+                  <span class="text-xs text-gray-400" title="<%= format_duration(offset) %> from start">
+                    <% if offset < 0.001 %>
+                      0
+                    <% elsif offset < 1 %>
+                      +<%= (offset * 1000).round %>ms
+                    <% elsif offset < 60 %>
+                      +<%= offset.round(1) %>s
+                    <% else %>
+                      +<%= (offset / 60).round %>m
+                    <% end %>
+                  </span>
+                </div>
+              <% end %>
+
+              <div class="flex items-start justify-between">
+                <div class="flex-1 min-w-0">
+                  <!-- Event name badge -->
+                  <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-indigo-100 text-indigo-800">
+                    <%= event_name(event) %>
+                  </span>
+
+                  <!-- Payload preview -->
+                  <% payload = event_payload(event) %>
+                  <% if payload.present? && payload.any? %>
+                    <div class="mt-2">
+                      <code class="text-xs bg-gray-100 px-2 py-1 rounded text-gray-600">
+                        <%= truncate_json(payload, length: 100) %>
+                      </code>
+                    </div>
+                  <% end %>
+
+                  <!-- Tags -->
+                  <% tags = event_tags(event) %>
+                  <% if tags.present? && tags.any? %>
+                    <div class="mt-2 flex flex-wrap gap-1">
+                      <% tags.first(3).each do |key, value| %>
+                        <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-gray-100 text-gray-700">
+                          <%= key %>: <%= value.to_s.truncate(20) %>
+                        </span>
+                      <% end %>
+                      <% if tags.size > 3 %>
+                        <span class="text-xs text-gray-500">+<%= tags.size - 3 %> more</span>
+                      <% end %>
+                    </div>
+                  <% end %>
+                </div>
+
+                <div class="ml-4 flex-shrink-0 text-right">
+                  <p class="text-sm text-gray-500">
+                    <%= time_ago_with_title(event_occurred_at(event)) %>
+                  </p>
+                  <% if event_source_file(event).present? %>
+                    <p class="text-xs text-gray-400 mt-1">
+                      <%= event_short_filepath(event) %>:<%= event_source_line(event) %>
+                    </p>
+                  <% end %>
+                </div>
+              </div>
+            </a>
+          <% end %>
+        </div>
+      </div>
+
+      <%= render "rails_event_viewer/shared/pagination", pagy: @pagy %>
+    <% else %>
+      <div class="px-6 py-12 text-center text-gray-500">
+        No events found in this group.
+      </div>
+    <% end %>
+  </div>
+</div>

data/app/views/rails_event_viewer/shared/_navigation.html.erb

@@ -0,0 +1,47 @@
+<nav class="bg-indigo-600">
+  <div class="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+    <div class="flex h-16 items-center justify-between">
+      <div class="flex items-center">
+        <div class="flex-shrink-0">
+          <%= link_to rails_event_viewer.root_path, class: "text-white text-xl font-bold" do %>
+            Event Viewer
+          <% end %>
+        </div>
+        <div class="ml-10 flex items-baseline space-x-4">
+          <%= link_to "Dashboard", rails_event_viewer.root_path,
+              class: nav_link_class("dashboard") %>
+          <%= link_to "Events", rails_event_viewer.events_path,
+              class: nav_link_class("events") %>
+          <%= link_to "Event Types", rails_event_viewer.event_types_path,
+              class: nav_link_class("event_types") %>
+          <%= link_to "Groups", rails_event_viewer.groups_path,
+              class: nav_link_class("groups") %>
+          <%= link_to "Analytics", rails_event_viewer.analytics_overview_path,
+              class: nav_link_class("analytics") %>
+        </div>
+      </div>
+
+      <div class="flex items-center space-x-4">
+        <!-- Search -->
+        <%= form_with url: rails_event_viewer.search_events_path, method: :get, class: "relative", data: { turbo_frame: "_top" } do |f| %>
+          <div class="relative">
+            <div class="pointer-events-none absolute inset-y-0 left-0 flex items-center pl-3">
+              <svg class="h-4 w-4 text-indigo-200" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+              </svg>
+            </div>
+            <%= f.search_field :q,
+                value: params[:q],
+                placeholder: "Search events...",
+                class: "w-64 rounded-md bg-indigo-500 py-2 pl-10 pr-3 text-sm text-white placeholder-indigo-200 focus:bg-white focus:text-gray-900 focus:placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-white" %>
+          </div>
+        <% end %>
+
+        <!-- Timezone indicator -->
+        <div class="text-indigo-200 text-sm" title="Current timezone">
+          <%= Time.zone.name %>
+        </div>
+      </div>
+    </div>
+  </div>
+</nav>

data/app/views/rails_event_viewer/shared/_pagination.html.erb

@@ -0,0 +1,60 @@
+<% if pagy.pages > 1 %>
+  <div class="bg-white px-4 py-3 flex items-center justify-between border-t border-gray-200 sm:px-6">
+    <div class="flex-1 flex items-center justify-between">
+      <div>
+        <p class="text-sm text-gray-700">
+          Showing
+          <span class="font-medium"><%= pagy.from %></span>
+          to
+          <span class="font-medium"><%= pagy.to %></span>
+          of
+          <span class="font-medium"><%= pagy.count %></span>
+          results
+        </p>
+      </div>
+      <nav class="flex items-center space-x-1" aria-label="Pagination">
+        <% if pagy.previous %>
+          <%= link_to url_for(page: pagy.previous), class: "relative inline-flex items-center px-3 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50" do %>
+            <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7" />
+            </svg>
+            <span class="ml-1">Prev</span>
+          <% end %>
+        <% else %>
+          <span class="relative inline-flex items-center px-3 py-2 text-sm font-medium text-gray-300 bg-white border border-gray-200 rounded-md cursor-not-allowed">
+            <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7" />
+            </svg>
+            <span class="ml-1">Prev</span>
+          </span>
+        <% end %>
+
+        <% (1..pagy.pages).each do |page_num| %>
+          <% if page_num == pagy.page %>
+            <span class="relative inline-flex items-center px-3 py-2 text-sm font-medium text-white bg-indigo-600 border border-indigo-600 rounded-md"><%= page_num %></span>
+          <% elsif page_num == 1 || page_num == pagy.pages || (page_num >= pagy.page - 2 && page_num <= pagy.page + 2) %>
+            <%= link_to page_num, url_for(page: page_num), class: "relative inline-flex items-center px-3 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50" %>
+          <% elsif page_num == pagy.page - 3 || page_num == pagy.page + 3 %>
+            <span class="relative inline-flex items-center px-2 py-2 text-sm font-medium text-gray-700">...</span>
+          <% end %>
+        <% end %>
+
+        <% if pagy.next %>
+          <%= link_to url_for(page: pagy.next), class: "relative inline-flex items-center px-3 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50" do %>
+            <span class="mr-1">Next</span>
+            <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
+            </svg>
+          <% end %>
+        <% else %>
+          <span class="relative inline-flex items-center px-3 py-2 text-sm font-medium text-gray-300 bg-white border border-gray-200 rounded-md cursor-not-allowed">
+            <span class="mr-1">Next</span>
+            <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
+            </svg>
+          </span>
+        <% end %>
+      </nav>
+    </div>
+  </div>
+<% end %>

data/app/views/rails_event_viewer/shared/_stat_card.html.erb

@@ -0,0 +1,36 @@
+<div class="bg-white overflow-hidden shadow rounded-lg">
+  <div class="p-5">
+    <div class="flex items-center">
+      <div class="flex-shrink-0">
+        <% case icon %>
+        <% when "database" %>
+          <svg class="h-6 w-6 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 7v10c0 2.21 3.582 4 8 4s8-1.79 8-4V7M4 7c0 2.21 3.582 4 8 4s8-1.79 8-4M4 7c0-2.21 3.582-4 8-4s8 1.79 8 4m0 5c0 2.21-3.582 4-8 4s-8-1.79-8-4" />
+          </svg>
+        <% when "calendar" %>
+          <svg class="h-6 w-6 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 7V3m8 4V3m-9 8h10M5 21h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z" />
+          </svg>
+        <% when "tag" %>
+          <svg class="h-6 w-6 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A1.994 1.994 0 013 12V7a4 4 0 014-4z" />
+          </svg>
+        <% when "clock" %>
+          <svg class="h-6 w-6 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
+          </svg>
+        <% else %>
+          <svg class="h-6 w-6 text-gray-400" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z" />
+          </svg>
+        <% end %>
+      </div>
+      <div class="ml-5 w-0 flex-1">
+        <dl>
+          <dt class="text-sm font-medium text-gray-500 truncate"><%= title %></dt>
+          <dd class="text-lg font-semibold text-gray-900"><%= value %></dd>
+        </dl>
+      </div>
+    </div>
+  </div>
+</div>

data/config/routes.rb

@@ -0,0 +1,18 @@
+RailsEventViewer::Engine.routes.draw do
+  root to: "dashboard#index"
+
+  resources :events, only: [:index, :show] do
+    collection do
+      get :search
+    end
+  end
+
+  namespace :analytics do
+    get :overview
+    get :events_over_time
+    get :events_by_type
+  end
+
+  resources :event_types, only: [:index, :show], param: :name
+  resources :groups, only: [:index, :show]
+end

data/db/migrate/20241208000001_create_rails_event_viewer_entries.rb

@@ -0,0 +1,36 @@
+class CreateRailsEventViewerEntries < ActiveRecord::Migration[8.0]
+  def change
+    create_table :rails_event_viewer_entries do |t|
+      t.string :name, null: false
+
+      # Use jsonb for PostgreSQL (better performance), json for others (SQLite, MySQL)
+      json_type = postgresql? ? :jsonb : :json
+      t.column :payload, json_type, default: {}
+      t.column :tags, json_type, default: {}
+      t.column :context, json_type, default: {}
+
+      t.string :source_file
+      t.integer :source_line
+      t.string :source_label
+      t.datetime :occurred_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :rails_event_viewer_entries, :name
+    add_index :rails_event_viewer_entries, :occurred_at
+    add_index :rails_event_viewer_entries, [:name, :occurred_at]
+
+    # GIN index for JSONB columns (PostgreSQL only)
+    if postgresql?
+      add_index :rails_event_viewer_entries, :tags, using: :gin
+      add_index :rails_event_viewer_entries, :context, using: :gin
+    end
+  end
+
+  private
+
+  def postgresql?
+    connection.adapter_name.downcase.include?("postgresql")
+  end
+end

data/lib/generators/rails_event_viewer/install/USAGE

@@ -0,0 +1,33 @@
+Description:
+    Installs RailsEventViewer into your Rails application.
+
+    This will:
+    - Create a migration for the events table (if using ActiveRecord adapter)
+    - Create an initializer with configuration options
+    - Mount the engine in your routes file
+
+Example:
+    bin/rails generate rails_event_viewer:install
+
+    This will create:
+        db/migrate/YYYYMMDDHHMMSS_create_rails_event_viewer_entries.rb
+        config/initializers/rails_event_viewer.rb
+
+    And add to config/routes.rb:
+        mount RailsEventViewer::Engine, at: "/events"
+
+Options:
+    --storage-adapter=ADAPTER  # Storage adapter to use: active_record (default), redis, memory
+    --skip-migration           # Skip creating the migration file
+    --skip-initializer         # Skip creating the initializer
+    --skip-routes              # Skip mounting the engine in routes
+
+Examples:
+    # Standard install with ActiveRecord
+    bin/rails generate rails_event_viewer:install
+
+    # Install with Redis adapter (no migration needed)
+    bin/rails generate rails_event_viewer:install --storage-adapter=redis
+
+    # Only create initializer (skip migration and routes)
+    bin/rails generate rails_event_viewer:install --skip-migration --skip-routes

data/lib/generators/rails_event_viewer/install/install_generator.rb

@@ -0,0 +1,86 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RailsEventViewer
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs RailsEventViewer: creates migration, initializer, and mounts the engine"
+
+      class_option :storage_adapter, type: :string, default: "active_record",
+        desc: "Storage adapter to use (active_record, redis, memory)"
+
+      class_option :skip_migration, type: :boolean, default: false,
+        desc: "Skip creating the migration file"
+
+      class_option :skip_initializer, type: :boolean, default: false,
+        desc: "Skip creating the initializer file"
+
+      class_option :skip_routes, type: :boolean, default: false,
+        desc: "Skip mounting the engine in routes"
+
+      def create_migration_file
+        return if options[:skip_migration]
+        return if options[:storage_adapter] != "active_record"
+
+        migration_template(
+          "create_rails_event_viewer_entries.rb.erb",
+          "db/migrate/create_rails_event_viewer_entries.rb"
+        )
+      end
+
+      def create_initializer
+        return if options[:skip_initializer]
+
+        template(
+          "initializer.rb.erb",
+          "config/initializers/rails_event_viewer.rb"
+        )
+      end
+
+      def mount_engine
+        return if options[:skip_routes]
+
+        route_line = 'mount RailsEventViewer::Engine, at: "/events"'
+
+        routes_file = File.join(destination_root, "config/routes.rb")
+        if File.exist?(routes_file) && File.read(routes_file).include?("RailsEventViewer::Engine")
+          say_status :skip, "Engine already mounted in routes", :yellow
+          return
+        end
+
+        route route_line
+      end
+
+      def show_post_install_message
+        say ""
+        say "RailsEventViewer has been installed!", :green
+        say ""
+        say "Next steps:"
+
+        if options[:storage_adapter] == "active_record" && !options[:skip_migration]
+          say "  1. Run migrations: rails db:migrate"
+        end
+
+        say "  2. Configure authentication in config/initializers/rails_event_viewer.rb"
+        say "  3. Visit /events to view your events"
+        say ""
+        say "For more information, visit: https://github.com/keshavbiswa/rails_event_viewer"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+
+      def storage_adapter
+        options[:storage_adapter]
+      end
+    end
+  end
+end

data/lib/generators/rails_event_viewer/install/templates/create_rails_event_viewer_entries.rb.erb

@@ -0,0 +1,35 @@
+class CreateRailsEventViewerEntries < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :rails_event_viewer_entries do |t|
+      t.string :name, null: false
+
+      json_type = postgresql? ? :jsonb : :json
+      t.column :payload, json_type, default: {}
+      t.column :tags, json_type, default: {}
+      t.column :context, json_type, default: {}
+
+      t.string :source_file
+      t.integer :source_line
+      t.string :source_label
+      t.datetime :occurred_at, null: false
+
+      t.timestamps
+    end
+
+    add_index :rails_event_viewer_entries, :name
+    add_index :rails_event_viewer_entries, :occurred_at
+    add_index :rails_event_viewer_entries, [:name, :occurred_at]
+
+    # GIN index for JSONB columns (PostgreSQL only)
+    if postgresql?
+      add_index :rails_event_viewer_entries, :tags, using: :gin
+      add_index :rails_event_viewer_entries, :context, using: :gin
+    end
+  end
+
+  private
+
+  def postgresql?
+    connection.adapter_name.downcase.include?("postgresql")
+  end
+end