feat(ui): add avg-by-hour panel to dashboard stats

Complements the existing avg-by-weekday chart with its orthogonal
partner: which hour of the day the user typically commits. The api
buckets events by EXTRACT(hour FROM occurred_at AT TIME ZONE $tz) so
the chart matches the clock the user sees rather than UTC; the UI
passes the browser's resolved IANA timezone. Renders as 24 mini-bars
below the weekday chart with labels every 4 hours and per-bar
tooltips showing the average events/day at that hour.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

crates/moments-api/src/main.rs

@@ -11,7 +11,7 @@ use chrono::{DateTime, Datelike, NaiveDate, Utc};
 use clap::Parser;
 use moments_core::{EventReader, reshape};
 use moments_data::PgStore;
-use moments_entities::{DailyCount, EventQuery, LanguageDailyCount, ProjectSummary, RepoLanguage, Source, SourceSummary, TimelineItem};
+use moments_entities::{DailyCount, EventQuery, HourlyAvg, LanguageDailyCount, ProjectSummary, RepoLanguage, Source, SourceSummary, TimelineItem};
 use serde::Deserialize;
 use tower_http::{cors::CorsLayer, trace::TraceLayer};
 use tracing::info;
@@ -57,6 +57,7 @@ async fn main() -> anyhow::Result<()> {
         .route("/v1/sources", get(list_sources))
         .route("/v1/projects", get(list_projects))
         .route("/v1/activity/daily", get(daily_counts))
+        .route("/v1/activity/hourly", get(hourly_avgs))
         .route("/v1/languages/daily", get(language_daily_counts))
         .route("/v1/languages/repos", get(repo_languages))
         .route("/v1/forge/{source}/{*rest}", get(forge_proxy))
@@ -169,6 +170,38 @@ async fn language_daily_counts(
     Ok(Json(counts))
 }
 
+#[derive(Debug, Deserialize)]
+struct HourlyAvgsParams {
+    from: Option<NaiveDate>,
+    to: Option<NaiveDate>,
+    /// IANA timezone name (e.g. "Europe/Helsinki"). Defaults to UTC.
+    /// Hour buckets are computed in this zone so the chart matches the
+    /// clock the user sees.
+    tz: Option<String>,
+}
+
+async fn hourly_avgs(
+    State(state): State<AppState>,
+    Query(params): Query<HourlyAvgsParams>,
+) -> Result<Json<Vec<HourlyAvg>>, ApiError> {
+    let to = params.to.unwrap_or_else(|| Utc::now().date_naive());
+    let from = params.from.unwrap_or_else(|| to - chrono::Duration::days(365));
+    let tz = params.tz.as_deref().unwrap_or("UTC");
+    // Validate the tz string before handing it to postgres — a bad name
+    // here would surface as an opaque 500 from the DB. chrono-tz would do
+    // it for free but we don't depend on it; instead reject obvious shell
+    // injection vectors (the value is bound, not interpolated, so this is
+    // belt-and-braces).
+    if tz.len() > 64 || tz.chars().any(|c| !(c.is_ascii_alphanumeric() || matches!(c, '/' | '_' | '+' | '-'))) {
+        return Err(ApiError {
+            status: StatusCode::BAD_REQUEST,
+            message: "invalid tz".into(),
+        });
+    }
+    let avgs = state.store.hourly_avgs(from, to, tz, /* include_private */ true).await.map_err(internal)?;
+    Ok(Json(avgs))
+}
+
 async fn repo_languages(
     State(state): State<AppState>,
 ) -> Result<Json<Vec<RepoLanguage>>, ApiError> {

crates/moments-core/src/lib.rs

@@ -6,7 +6,7 @@ pub use sources::{EventSource, PollerState, PollerStateStore, SourceError, run_p
 
 use async_trait::async_trait;
 use chrono::NaiveDate;
-use moments_entities::{DailyCount, Event, EventQuery, LanguageDailyCount, ProjectSummary, RepoLanguage, SourceSummary};
+use moments_entities::{DailyCount, Event, EventQuery, HourlyAvg, LanguageDailyCount, ProjectSummary, RepoLanguage, SourceSummary};
 
 #[derive(Debug, thiserror::Error)]
 pub enum StoreError {
@@ -22,6 +22,7 @@ pub trait EventReader: Send + Sync {
     async fn list_projects(&self) -> Result<Vec<ProjectSummary>, StoreError>;
     async fn daily_counts(&self, from: NaiveDate, to: NaiveDate, include_private: bool) -> Result<Vec<DailyCount>, StoreError>;
     async fn language_daily_counts(&self, from: NaiveDate, to: NaiveDate, include_private: bool) -> Result<Vec<LanguageDailyCount>, StoreError>;
+    async fn hourly_avgs(&self, from: NaiveDate, to: NaiveDate, tz: &str, include_private: bool) -> Result<Vec<HourlyAvg>, StoreError>;
     async fn repo_languages(&self) -> Result<Vec<RepoLanguage>, StoreError>;
 }
 

crates/moments-data/src/lib.rs

@@ -9,7 +9,7 @@ use async_trait::async_trait;
 use chrono::{DateTime, Utc};
 use moments_core::{EventReader, EventWriter, PollerState, PollerStateStore, StoreError};
 use chrono::NaiveDate;
-use moments_entities::{DailyCount, Event, EventQuery, LanguageDailyCount, ProjectSummary, RepoLanguage, Source, SourceSummary};
+use moments_entities::{DailyCount, Event, EventQuery, HourlyAvg, LanguageDailyCount, ProjectSummary, RepoLanguage, Source, SourceSummary};
 use sqlx::Row;
 use sqlx::postgres::{PgPool, PgPoolOptions};
 use std::str::FromStr;
@@ -291,6 +291,55 @@ impl EventReader for PgStore {
             .collect()
     }
 
+    async fn hourly_avgs(
+        &self,
+        from: NaiveDate,
+        to: NaiveDate,
+        tz: &str,
+        include_private: bool,
+    ) -> Result<Vec<HourlyAvg>, StoreError> {
+        // GREATEST guards against from > to (returns NaN-via-div-by-zero
+        // otherwise). EXTRACT(hour FROM tz-shifted timestamp) buckets each
+        // event into the user's local hour rather than UTC, so the chart
+        // matches the labels they'd see on a clock.
+        let rows = sqlx::query(
+            r#"
+            WITH params AS (
+                SELECT GREATEST(($2::date - $1::date + 1), 1)::float8 AS day_count
+            ),
+            bucketed AS (
+                SELECT EXTRACT(hour FROM (occurred_at AT TIME ZONE $3))::int AS hour
+                FROM events
+                WHERE occurred_at >= ($1::date::timestamp AT TIME ZONE 'UTC')
+                  AND occurred_at <  (($2::date + 1)::timestamp AT TIME ZONE 'UTC')
+                  AND ($4::bool OR public = true)
+            )
+            SELECT g.h::int AS hour,
+                   (COUNT(b.hour)::float8 / (SELECT day_count FROM params)) AS avg
+            FROM generate_series(0, 23) AS g(h)
+            LEFT JOIN bucketed b ON b.hour = g.h
+            GROUP BY g.h
+            ORDER BY g.h
+            "#,
+        )
+        .bind(from)
+        .bind(to)
+        .bind(tz)
+        .bind(include_private)
+        .fetch_all(&self.pool)
+        .await
+        .map_err(map_err)?;
+
+        rows.into_iter()
+            .map(|r| {
+                Ok(HourlyAvg {
+                    hour: r.try_get("hour").map_err(map_err)?,
+                    avg: r.try_get("avg").map_err(map_err)?,
+                })
+            })
+            .collect()
+    }
+
     async fn repo_languages(&self) -> Result<Vec<RepoLanguage>, StoreError> {
         let rows = sqlx::query(
             r#"

crates/moments-entities/src/lib.rs

@@ -91,6 +91,14 @@ pub struct DailyCount {
     pub count: i64,
 }
 
+/// Average events per day at a given hour of the day, computed in a
+/// caller-supplied IANA timezone. 24 entries (0..=23).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct HourlyAvg {
+    pub hour: i32,
+    pub avg: f64,
+}
+
 /// Per-repo activity rollup for the dashboard.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ProjectSummary {