quarterdeck 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 84e4ec81af825568dd7458fba3c8a209ebce868478a15db046e0ebc17bcbd1e7
+  data.tar.gz: f1f269be8224650baa0aea62679cdf0bddea64c43536e31c7d8c46acb2bd4ff6
+SHA512:
+  metadata.gz: edfde0d7b87eefa9eb730baac6f3bf1cf7d781ca07e89414316f5606afac90bbc7aaffc18f2b22501e1b0b5f38f878797fe74ee8d28f1edcd2403c256ffcf191
+  data.tar.gz: 845bae97704d3c2aafb59bc1d377647207efa5cf33880583bd788778bb289779b6d185afff3c9f793fecef32217deb7f90ddd4734d71d94a5ad8a0b20cee651b

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright leopolicastro
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,93 @@
+# Quarterdeck
+
+A beautiful analytics dashboard engine for Rails apps already using [ahoy_matey](https://github.com/ankane/ahoy) for tracking. Quarterdeck reads your existing Ahoy data and presents it in a modern dashboard with charts, tables, and filters.
+
+No database migrations needed — Quarterdeck reads directly from your `ahoy_visits` and `ahoy_events` tables.
+
+## Features
+
+- **Overview** — Total visits, unique visitors, events, daily chart, top pages, referrers, browsers, devices, OS, countries, campaigns
+- **Visits** — Searchable/filterable visit log with pagination and detail views
+- **Events** — Event breakdown with daily chart, filtering by event name
+- **Campaigns** — UTM breakdowns (source, medium, campaign, term, content) with charts
+- **Geographic** — Country, region, and city breakdowns with charts
+- **Live** — Real-time active visitors, current pages, and live event stream
+- **Trend comparisons** — Stat cards show % change vs previous period
+- **Custom date ranges** — Pick arbitrary start/end dates alongside preset periods
+- **CSV export** — Download data from any page
+
+Built with Tailwind CSS, Chart.js, and Stimulus.
+
+## Requirements
+
+Your Rails app must have the following set up before installing Quarterdeck:
+
+- **Rails 8.1+**
+- **[ahoy_matey](https://github.com/ankane/ahoy) 4+** — already installed and tracking visits/events
+- **[importmap-rails](https://github.com/rails/importmap-rails)** — for JavaScript module loading
+- **[stimulus-rails](https://github.com/hotwired/stimulus-rails)** — for interactive UI components
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "quarterdeck"
+```
+
+Run the install generator:
+
+```bash
+bundle install
+rails generate quarterdeck:install
+```
+
+This will:
+1. Create `config/initializers/quarterdeck.rb`
+2. Mount the engine at `/analytics` in your routes
+
+Or set up manually:
+
+```ruby
+# config/routes.rb
+mount Quarterdeck::Engine => "/analytics"
+```
+
+## Configuration
+
+```ruby
+# config/initializers/quarterdeck.rb
+
+# Require authentication
+Quarterdeck.authenticate_with do
+  redirect_to main_app.root_path unless current_user&.admin?
+end
+```
+
+## Pages
+
+| Path | Description |
+|------|-------------|
+| `/analytics` | Overview dashboard |
+| `/analytics/visits` | Visit log with filters |
+| `/analytics/visits/:id` | Visit detail with events |
+| `/analytics/events` | Event breakdown |
+| `/analytics/campaigns` | UTM campaign analysis |
+| `/analytics/geographic` | Geographic breakdown |
+| `/analytics/live` | Real-time active visitors |
+
+All pages support period filtering: Today, 7 days, 30 days, 90 days, or a custom date range.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+
+[![Certified Shovelware](https://justin.searls.co/img/shovelware.svg)](https://justin.searls.co/shovelware/)

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/quarterdeck/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/quarterdeck/application_controller.rb

@@ -0,0 +1,73 @@
+require "csv"
+
+module Quarterdeck
+  class ApplicationController < ActionController::Base
+    include Pagy::Method
+
+    before_action :authenticate_quarterdeck!
+
+    helper_method :period, :period_range, :previous_period_range
+
+    private
+
+    def authenticate_quarterdeck!
+      if Quarterdeck.authentication_block
+        instance_exec(&Quarterdeck.authentication_block)
+      end
+    end
+
+    def period
+      @period ||= params[:period].presence || "30d"
+    end
+
+    def period_range
+      @period_range ||= case period
+      when "today"
+        Time.current.beginning_of_day..Time.current
+      when "7d"
+        7.days.ago.beginning_of_day..Time.current
+      when "30d"
+        30.days.ago.beginning_of_day..Time.current
+      when "90d"
+        90.days.ago.beginning_of_day..Time.current
+      when "custom"
+        start_date = Date.parse(params[:start_date]).beginning_of_day
+        end_date = Date.parse(params[:end_date]).end_of_day
+        start_date..end_date
+      else
+        30.days.ago.beginning_of_day..Time.current
+      end
+    end
+
+    def previous_period_range
+      @previous_period_range ||= begin
+        duration = period_range.last - period_range.first
+        (period_range.first - duration)..period_range.first
+      end
+    end
+
+    def visits_in_period
+      @visits_in_period ||= Ahoy::Visit.where(started_at: period_range)
+    end
+
+    def events_in_period
+      @events_in_period ||= Ahoy::Event.where(time: period_range)
+    end
+
+    def previous_visits
+      Ahoy::Visit.where(started_at: previous_period_range)
+    end
+
+    def previous_events
+      Ahoy::Event.where(time: previous_period_range)
+    end
+
+    def send_csv(filename, headers, rows)
+      csv_data = CSV.generate(headers: true) do |csv|
+        csv << headers
+        rows.each { |row| csv << row }
+      end
+      send_data csv_data, filename: "#{filename}-#{Date.current}.csv", type: "text/csv"
+    end
+  end
+end

data/app/controllers/quarterdeck/campaigns_controller.rb

@@ -0,0 +1,52 @@
+module Quarterdeck
+  class CampaignsController < ApplicationController
+    def show
+      campaign_visits = visits_in_period.where.not(utm_source: [ nil, "" ])
+
+      @total_campaign_visits = campaign_visits.count
+
+      @sources = campaign_visits
+        .group(:utm_source)
+        .order(Arel.sql("count(*) DESC"))
+        .count
+
+      @mediums = campaign_visits
+        .where.not(utm_medium: [ nil, "" ])
+        .group(:utm_medium)
+        .order(Arel.sql("count(*) DESC"))
+        .count
+
+      @campaigns = campaign_visits
+        .where.not(utm_campaign: [ nil, "" ])
+        .group(:utm_campaign)
+        .order(Arel.sql("count(*) DESC"))
+        .count
+
+      @terms = campaign_visits
+        .where.not(utm_term: [ nil, "" ])
+        .group(:utm_term)
+        .order(Arel.sql("count(*) DESC"))
+        .count
+
+      @contents = campaign_visits
+        .where.not(utm_content: [ nil, "" ])
+        .group(:utm_content)
+        .order(Arel.sql("count(*) DESC"))
+        .count
+
+      respond_to do |format|
+        format.html
+        format.csv do
+          rows = []
+          rows << ["--- Sources ---", ""]
+          @sources.each { |s, c| rows << [s, c] }
+          rows << ["--- Mediums ---", ""]
+          @mediums.each { |m, c| rows << [m, c] }
+          rows << ["--- Campaigns ---", ""]
+          @campaigns.each { |camp, c| rows << [camp, c] }
+          send_csv("campaigns", ["Item", "Visits"], rows)
+        end
+      end
+    end
+  end
+end

data/app/controllers/quarterdeck/events_controller.rb

@@ -0,0 +1,38 @@
+module Quarterdeck
+  class EventsController < ApplicationController
+    def index
+      scope = events_in_period.order(time: :desc)
+
+      if params[:name].present?
+        scope = scope.where(name: params[:name])
+      end
+
+      @total_events = scope.count
+      @unique_events = scope.distinct.count(:name)
+
+      prev_scope = previous_events
+      prev_scope = prev_scope.where(name: params[:name]) if params[:name].present?
+      @prev_total_events = prev_scope.count
+      @prev_unique_events = prev_scope.distinct.count(:name)
+
+      @daily_events = scope
+        .group_by_day(:time)
+        .count
+
+      @event_names = events_in_period
+        .group(:name)
+        .order(Arel.sql("count(*) DESC"))
+        .count
+
+      respond_to do |format|
+        format.html do
+          @pagy, @events = pagy(:offset, scope, limit: 25)
+        end
+        format.csv do
+          rows = @event_names.map { |name, count| [name, count] }
+          send_csv("events", ["Event Name", "Count"], rows)
+        end
+      end
+    end
+  end
+end

data/app/controllers/quarterdeck/geographics_controller.rb

@@ -0,0 +1,41 @@
+module Quarterdeck
+  class GeographicsController < ApplicationController
+    def show
+      geo_visits = visits_in_period
+
+      @countries = geo_visits
+        .where.not(country: [ nil, "" ])
+        .group(:country)
+        .order(Arel.sql("count(*) DESC"))
+        .count
+
+      @regions = geo_visits
+        .where.not(region: [ nil, "" ])
+        .group(:region)
+        .order(Arel.sql("count(*) DESC"))
+        .limit(25)
+        .count
+
+      @cities = geo_visits
+        .where.not(city: [ nil, "" ])
+        .group(:city)
+        .order(Arel.sql("count(*) DESC"))
+        .limit(25)
+        .count
+
+      respond_to do |format|
+        format.html
+        format.csv do
+          rows = []
+          rows << ["--- Countries ---", ""]
+          @countries.each { |c, count| rows << [c, count] }
+          rows << ["--- Regions ---", ""]
+          @regions.each { |r, count| rows << [r, count] }
+          rows << ["--- Cities ---", ""]
+          @cities.each { |c, count| rows << [c, count] }
+          send_csv("geographic", ["Location", "Visits"], rows)
+        end
+      end
+    end
+  end
+end

data/app/controllers/quarterdeck/live_controller.rb

@@ -0,0 +1,32 @@
+module Quarterdeck
+  class LiveController < ApplicationController
+    def show
+      @active_visitors = Ahoy::Visit.where(started_at: 5.minutes.ago..Time.current).distinct.count(:visitor_token)
+      @current_pages = Ahoy::Event
+        .where(name: "$view", time: 5.minutes.ago..Time.current)
+        .group("properties->>'url'")
+        .order(Arel.sql("count(*) DESC"))
+        .limit(10)
+        .count
+      @recent_events = Ahoy::Event.order(time: :desc).limit(20).includes(:visit)
+
+      respond_to do |format|
+        format.html
+        format.json do
+          render json: {
+            active_visitors: @active_visitors,
+            current_pages: @current_pages.map { |url, count| { url: url, count: count } },
+            recent_events: @recent_events.map { |e|
+              {
+                time: e.time.strftime("%H:%M:%S"),
+                name: e.name,
+                properties: e.properties,
+                visitor: e.visit&.visitor_token&.first(8)
+              }
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/app/controllers/quarterdeck/overview_controller.rb

@@ -0,0 +1,89 @@
+module Quarterdeck
+  class OverviewController < ApplicationController
+    def show
+      @total_visits = visits_in_period.count
+      @unique_visitors = visits_in_period.distinct.count(:visitor_token)
+      @total_events = events_in_period.count
+
+      @prev_total_visits = previous_visits.count
+      @prev_unique_visitors = previous_visits.distinct.count(:visitor_token)
+      @prev_total_events = previous_events.count
+
+      @daily_visits = visits_in_period
+        .group_by_day(:started_at)
+        .count
+
+      @top_pages = events_in_period
+        .where(name: "$view")
+        .group("properties->>'url'")
+        .order(Arel.sql("count(*) DESC"))
+        .limit(10)
+        .count
+
+      @top_referrers = visits_in_period
+        .where.not(referring_domain: [ nil, "" ])
+        .group(:referring_domain)
+        .order(Arel.sql("count(*) DESC"))
+        .limit(10)
+        .count
+
+      @browsers = visits_in_period
+        .where.not(browser: [ nil, "" ])
+        .group(:browser)
+        .order(Arel.sql("count(*) DESC"))
+        .limit(10)
+        .count
+
+      @devices = visits_in_period
+        .where.not(device_type: [ nil, "" ])
+        .group(:device_type)
+        .order(Arel.sql("count(*) DESC"))
+        .limit(10)
+        .count
+
+      @os = visits_in_period
+        .where.not(os: [ nil, "" ])
+        .group(:os)
+        .order(Arel.sql("count(*) DESC"))
+        .limit(10)
+        .count
+
+      @countries = visits_in_period
+        .where.not(country: [ nil, "" ])
+        .group(:country)
+        .order(Arel.sql("count(*) DESC"))
+        .limit(10)
+        .count
+
+      @top_events = events_in_period
+        .where.not(name: "$view")
+        .group(:name)
+        .order(Arel.sql("count(*) DESC"))
+        .limit(10)
+        .count
+
+      @campaigns = visits_in_period
+        .where.not(utm_source: [ nil, "" ])
+        .group(:utm_source)
+        .order(Arel.sql("count(*) DESC"))
+        .limit(10)
+        .count
+
+      respond_to do |format|
+        format.html
+        format.csv do
+          rows = []
+          rows << ["--- Top Pages ---", ""]
+          @top_pages.each { |page, count| rows << [page, count] }
+          rows << ["--- Top Referrers ---", ""]
+          @top_referrers.each { |ref, count| rows << [ref, count] }
+          rows << ["--- Browsers ---", ""]
+          @browsers.each { |b, count| rows << [b, count] }
+          rows << ["--- Countries ---", ""]
+          @countries.each { |c, count| rows << [c, count] }
+          send_csv("overview", ["Item", "Count"], rows)
+        end
+      end
+    end
+  end
+end

data/app/controllers/quarterdeck/visits_controller.rb

@@ -0,0 +1,46 @@
+module Quarterdeck
+  class VisitsController < ApplicationController
+    def index
+      scope = visits_in_period.order(started_at: :desc)
+
+      if params[:search].present?
+        scope = scope.where(
+          "landing_page LIKE :q OR referring_domain LIKE :q OR ip LIKE :q",
+          q: "%#{params[:search]}%"
+        )
+      end
+
+      scope = scope.where(browser: params[:browser]) if params[:browser].present?
+      scope = scope.where(device_type: params[:device_type]) if params[:device_type].present?
+      scope = scope.where(os: params[:os]) if params[:os].present?
+      scope = scope.where(country: params[:country]) if params[:country].present?
+
+      if params[:utm_only] == "1"
+        scope = scope.where.not(utm_source: [ nil, "" ])
+      end
+
+      respond_to do |format|
+        format.html do
+          @pagy, @visits = pagy(:offset, scope, limit: 25)
+          @browsers = visits_in_period.where.not(browser: [ nil, "" ]).distinct.pluck(:browser).sort
+          @devices = visits_in_period.where.not(device_type: [ nil, "" ]).distinct.pluck(:device_type).sort
+          @operating_systems = visits_in_period.where.not(os: [ nil, "" ]).distinct.pluck(:os).sort
+          @countries_list = visits_in_period.where.not(country: [ nil, "" ]).distinct.pluck(:country).sort
+        end
+        format.csv do
+          visits = scope.limit(10_000)
+          headers = ["Started At", "Landing Page", "Referrer", "Browser", "Device", "OS", "Country", "City", "IP", "UTM Source", "UTM Medium", "UTM Campaign"]
+          rows = visits.map do |v|
+            [v.started_at, v.landing_page, v.referring_domain, v.browser, v.device_type, v.os, v.country, v.city, v.ip, v.utm_source, v.utm_medium, v.utm_campaign]
+          end
+          send_csv("visits", headers, rows)
+        end
+      end
+    end
+
+    def show
+      @visit = Ahoy::Visit.find(params[:id])
+      @events = @visit.events.order(time: :desc)
+    end
+  end
+end

data/app/helpers/quarterdeck/application_helper.rb

@@ -0,0 +1,4 @@
+module Quarterdeck
+  module ApplicationHelper
+  end
+end

data/app/javascript/quarterdeck/application.js

@@ -0,0 +1,9 @@
+import { Application } from "@hotwired/stimulus"
+import ChartController from "quarterdeck/controllers/chart_controller"
+import DateRangeController from "quarterdeck/controllers/date_range_controller"
+import LiveController from "quarterdeck/controllers/live_controller"
+
+const application = Application.start()
+application.register("chart", ChartController)
+application.register("date-range", DateRangeController)
+application.register("live", LiveController)

data/app/javascript/quarterdeck/controllers/chart_controller.js

@@ -0,0 +1,99 @@
+import { Controller } from "@hotwired/stimulus"
+import "chart.js/auto"
+
+export default class extends Controller {
+  static values = {
+    type: { type: String, default: "line" },
+    labels: Array,
+    data: Array,
+    label: { type: String, default: "" },
+    colors: Array
+  }
+
+  connect() {
+    this.buildChart()
+  }
+
+  disconnect() {
+    if (this.chart) {
+      this.chart.destroy()
+    }
+  }
+
+  buildChart() {
+    const ctx = this.element.getContext("2d")
+    const chartType = this.typeValue
+
+    const defaultColors = [
+      "#6366f1", "#818cf8", "#a5b4fc", "#c7d2fe", "#e0e7ff",
+      "#4f46e5", "#4338ca", "#3730a3", "#312e81", "#1e1b4b"
+    ]
+    const colors = this.hasColorsValue ? this.colorsValue : defaultColors
+
+    const config = {
+      type: chartType,
+      data: this.chartData(chartType, colors),
+      options: this.chartOptions(chartType)
+    }
+
+    const ChartJS = window.Chart
+    this.chart = new ChartJS(ctx, config)
+  }
+
+  chartData(type, colors) {
+    if (type === "doughnut" || type === "pie") {
+      return {
+        labels: this.labelsValue,
+        datasets: [{
+          data: this.dataValue,
+          backgroundColor: colors.slice(0, this.dataValue.length),
+          borderWidth: 0
+        }]
+      }
+    }
+
+    return {
+      labels: this.labelsValue,
+      datasets: [{
+        label: this.labelValue,
+        data: this.dataValue,
+        borderColor: "#6366f1",
+        backgroundColor: type === "bar" ? "#6366f1" : "rgba(99, 102, 241, 0.1)",
+        fill: type === "line",
+        tension: 0.3,
+        borderWidth: 2,
+        pointRadius: 2,
+        pointHoverRadius: 4
+      }]
+    }
+  }
+
+  chartOptions(type) {
+    const base = {
+      responsive: true,
+      maintainAspectRatio: false,
+      plugins: {
+        legend: {
+          display: type === "doughnut" || type === "pie",
+          position: "bottom"
+        }
+      }
+    }
+
+    if (type === "line" || type === "bar") {
+      base.scales = {
+        x: {
+          grid: { display: false },
+          ticks: { font: { size: 11 } }
+        },
+        y: {
+          beginAtZero: true,
+          grid: { color: "rgba(0,0,0,0.05)" },
+          ticks: { font: { size: 11 } }
+        }
+      }
+    }
+
+    return base
+  }
+}

data/app/javascript/quarterdeck/controllers/date_range_controller.js

@@ -0,0 +1,18 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static targets = ["startDate", "endDate"]
+
+  submit() {
+    const startDate = this.startDateTarget.value
+    const endDate = this.endDateTarget.value
+
+    if (startDate && endDate) {
+      const url = new URL(window.location.href)
+      url.searchParams.set("period", "custom")
+      url.searchParams.set("start_date", startDate)
+      url.searchParams.set("end_date", endDate)
+      window.location.href = url.toString()
+    }
+  }
+}