chore: general cleanup

Signed-off-by: Henry <mail@henrygressmann.de>

Author: explodingcamera

biome.json

@@ -4,7 +4,23 @@
 		"enabled": true,
 		"actions": {
 			"recommended": true,
-			"source": { "recommended": true, "organizeImports": "off" }
+			"source": {
+				"recommended": true,
+				"organizeImports": {
+					"level": "on",
+					"options": {
+						"groups": [
+							"**/*.css",
+							":BLANK_LINE:",
+							[":BUN:", ":NODE:", "astro", "astro/**", "@astrojs/**", "react", "react/**", "react-dom", "react-dom/**"],
+							["d3-*", "d3/**"],
+							[":PACKAGE_WITH_PROTOCOL:", ":PACKAGE:"],
+							":BLANK_LINE:",
+							[":ALIAS:", ":PATH:"]
+						]
+					}
+				}
+			}
 		}
 	},
 	"formatter": {
@@ -34,7 +50,13 @@
 				"noStaticElementInteractions": "off"
 			},
 			"style": {
-				"noDescendingSpecificity": "off"
+				"noDescendingSpecificity": "off",
+				"useImportType": {
+					"level": "on",
+					"options": {
+						"style": "separatedType"
+					}
+				}
 			},
 			"complexity": {
 				"noImportantStyles": "off"
@@ -58,6 +80,9 @@
 	"overrides": [
 		{
 			"includes": ["**/*.astro"],
+			"assist": {
+				"enabled": false
+			},
 			"linter": {
 				"rules": {
 					"correctness": {

src/app/core.rs

@@ -1,11 +1,11 @@
-pub mod entities;
-pub mod events;
-pub mod onboarding;
-pub mod projects;
+mod entities;
+mod events;
+mod onboarding;
+mod projects;
 pub mod reports;
-pub mod sessions;
-pub mod settings;
-pub mod users;
+mod sessions;
+mod settings;
+mod users;
 
 pub use entities::LiwanEntities;
 pub use events::{LiwanEvents, PruneStats};
@@ -16,4 +16,7 @@ pub use settings::{LiwanProjectSettings, LiwanSettings};
 pub use users::LiwanUsers;
 
 #[cfg(feature = "geoip")]
-pub mod geoip;
+mod geoip;
+
+#[cfg(feature = "geoip")]
+pub use geoip::{LiwanGeoIP, keep_updated};

src/app/core/entities.rs

@@ -52,7 +52,7 @@ impl LiwanEntities {
         Ok(entity.clone())
     }
 
-    /// Update an entity's projects
+    /// Update an entity's project memberships
     pub fn update_projects(&self, entity_id: &str, project_ids: &[String]) -> Result<()> {
         let mut conn = self.pool.get()?;
         let tx = conn.transaction()?;
@@ -67,7 +67,7 @@ impl LiwanEntities {
         Ok(())
     }
 
-    /// Delete an entity (does not remove associated events)
+    /// Delete an entity without removing associated events
     pub fn delete(&self, id: &str) -> Result<()> {
         let mut conn = self.pool.get()?;
         let tx = conn.transaction()?;

src/app/core/events.rs

@@ -39,7 +39,7 @@ impl LiwanEvents {
         Ok(Self { duckdb, sqlite, daily_salt: ArcSwap::new(daily_salt.into()).into(), visitor_group_rotation_hour })
     }
 
-    /// Get the visitor group salt, generating a new one after the daily local rotation time.
+    /// Get the visitor group salt, generating a new one after the daily local rotation time
     pub fn get_salt(&self) -> Result<String> {
         let (salt, updated_at) = &**self.daily_salt.load();
 
@@ -59,7 +59,7 @@ impl LiwanEvents {
         }
     }
 
-    /// Append events in batch
+    /// Append events in a batch and update session timing fields when needed
     pub fn append(&self, events: impl Iterator<Item = Event>) -> Result<()> {
         let conn = self.duckdb.get()?;
         let mut first_event_time = None;
@@ -85,7 +85,7 @@ impl LiwanEvents {
         Ok(())
     }
 
-    /// Start processing events from the given channel. Blocks until the channel is closed.
+    /// Start processing events from the given channel. Blocks until the channel is closed
     pub async fn process_events(&self, events_rx: Receiver<Event>) -> Result<()> {
         let (tx, rx) = tokio::sync::oneshot::channel();
         let events = self.clone();
@@ -139,6 +139,7 @@ impl LiwanEvents {
         }
     }
 
+    /// Preview or apply collection-setting pruning for a single entity
     pub fn prune_entity(
         &self,
         entity_id: &str,
@@ -234,14 +235,11 @@ fn should_rotate_salt(updated_at: DateTime<Utc>, rotation_hour: u8) -> bool {
     updated_at < latest_rotation.with_timezone(&Utc)
 }
 
-fn count_rows<P>(conn: &Connection, sql: &str, params: P) -> DuckResult<u64>
-where
-    P: duckdb::Params,
-{
+fn count_rows(conn: &Connection, sql: &str, params: impl duckdb::Params) -> DuckResult<u64> {
     conn.query_row(sql, params, |row| row.get(0))
 }
 
-pub fn update_event_times(conn: &Connection, from_time: DateTime<Utc>, entities: &[String]) -> DuckResult<()> {
+fn update_event_times(conn: &Connection, from_time: DateTime<Utc>, entities: &[String]) -> DuckResult<()> {
     if entities.is_empty() {
         return Ok(());
     }

src/app/core/geoip.rs

@@ -68,7 +68,7 @@ impl LiwanGeoIP {
         }
     }
 
-    // Lookup the IP address in the GeoIP database
+    /// Lookup an IP address in the loaded GeoIP database
     pub fn lookup(&self, ip: &IpAddr) -> Result<LookupResult> {
         let Some(reader) = &*self.reader.load() else {
             return Ok(Default::default());
@@ -80,7 +80,7 @@ impl LiwanGeoIP {
         Ok(LookupResult { city, country_code })
     }
 
-    // Check for updates and download the latest database if available
+    /// Check for updates and download the latest database if available
     pub async fn check_for_updates(&self) -> Result<()> {
         if self.downloading.swap(true, Ordering::Acquire) {
             return Ok(());
@@ -137,6 +137,7 @@ impl LiwanGeoIP {
         Ok(())
     }
 
+    /// Reload the database from disk (as long as no update is currently in progress)
     pub fn reload(&self) -> Result<()> {
         if self.downloading.load(Ordering::Acquire) {
             return Ok(());
@@ -148,6 +149,7 @@ impl LiwanGeoIP {
     }
 }
 
+/// Keep the GeoIP database refreshed and reload it after local file changes
 pub async fn keep_updated(geoip: Arc<LiwanGeoIP>) {
     let path: PathBuf = geoip.path.clone();
     let mut last_meta = get_file_meta(&path);

src/app/core/projects.rs

@@ -13,7 +13,7 @@ impl LiwanProjects {
         Self { pool }
     }
 
-    /// Link an entity to a project
+    /// Replace the entities associated with a project
     pub fn update_entities(&self, project_id: &str, entity_ids: &[String]) -> Result<()> {
         let mut conn = self.pool.get()?;
         let tx = conn.transaction()?;
@@ -122,7 +122,7 @@ impl LiwanProjects {
         Ok(project.clone())
     }
 
-    /// remove the project and all associated `project_entities`
+    /// Delete a project and its entity memberships
     pub fn delete(&self, id: &str) -> Result<()> {
         let mut conn = self.pool.get()?;
         let tx = conn.transaction()?;

src/app/core/reports/dimension.rs

@@ -8,6 +8,7 @@ use duckdb::params_from_iter;
 use super::shared::{SESSION_DURATION_SQL, build_filter_clause, metric_aggregate_sql};
 use super::{DateRange, Dimension, DimensionFilter, Metric, ReportTable};
 
+/// Build a dimension table report for a metric
 pub fn dimension_report(
     conn: &DuckDBConn,
     entities: &[String],

src/app/core/reports/graph.rs

@@ -47,6 +47,7 @@ fn resolve_local_day_start(timezone: Tz, date: NaiveDate) -> Result<DateTime<Utc
     Ok(resolved.with_timezone(&Utc))
 }
 
+/// Split a date range into graph buckets aligned to the selected timezone
 pub fn build_graph_buckets(
     range: &DateRange,
     interval: GraphInterval,
@@ -96,6 +97,7 @@ pub fn build_graph_buckets(
     Ok(buckets)
 }
 
+/// Build a graph report for a metric across precomputed time buckets
 pub fn overall_report(
     conn: &DuckDBConn,
     entities: &[String],

src/app/core/reports/mod.rs

@@ -17,20 +17,25 @@ pub use crate::app::models::FilterType;
 
 #[derive(Serialize, Deserialize, JsonSchema, Debug, Clone, Hash, PartialEq, Eq)]
 pub struct DateRange {
+    /// Start of the report range
     pub start: DateTime<Utc>,
+    /// End of the report range
     pub end: DateTime<Utc>,
 }
 
 impl DateRange {
+    /// Return the immediately preceding range with the same duration
     pub fn prev(&self) -> Self {
         let duration = self.end - self.start;
         Self { start: self.start - duration, end: self.start }
     }
 
+    /// Return whether the range ends after the current time
     pub fn ends_in_future(&self) -> bool {
         self.end > Utc::now()
     }
 
+    /// Return the range duration
     pub fn duration(&self) -> chrono::Duration {
         self.end - self.start
     }
@@ -45,9 +50,13 @@ impl Display for DateRange {
 #[derive(Debug, Serialize, Deserialize, JsonSchema, Clone, Copy, PartialEq, Eq, Hash)]
 #[serde(rename_all = "snake_case")]
 pub enum Metric {
+    /// Total pageviews
     Views,
+    /// Distinct visitor groups
     UniqueVisitors,
+    /// Percentage of sessions with one pageview
     BounceRate,
+    /// Average time between pageviews in a session
     AvgTimeOnSite,
 }
 
@@ -62,33 +71,62 @@ impl Display for Metric {
     }
 }
 
+impl Metric {
+    /// Return all report metrics in dashboard order
+    pub const fn all() -> &'static [Self] {
+        &[Self::Views, Self::UniqueVisitors, Self::BounceRate, Self::AvgTimeOnSite]
+    }
+}
+
+/// Time bucket size for graph reports
 #[derive(Debug, Serialize, Deserialize, JsonSchema, Clone, Copy, PartialEq, Eq, Hash)]
 #[serde(rename_all = "snake_case")]
 pub enum GraphInterval {
+    /// Hourly buckets
     Hour,
+    /// Daily buckets
     Day,
 }
 
+/// Dimension selected for table reports and filters
 #[derive(Debug, Serialize, Deserialize, JsonSchema, Clone, Copy, Hash, Eq, PartialEq, PartialOrd, Ord)]
 #[serde(rename_all = "snake_case")]
 pub enum Dimension {
+    /// Full tracked URL
     Url,
+    /// First URL in a session
     UrlEntry,
+    /// Last URL in a session
     UrlExit,
+    /// Tracked hostname
     Fqdn,
+    /// Tracked path
     Path,
+    /// Referrer domain
     Referrer,
+    /// Operating system family
     Platform,
+    /// Browser family
     Browser,
+    /// Device type
     Mobile,
+    /// GeoIP country
     Country,
+    /// GeoIP city
     City,
+    /// UTM source
     UtmSource,
+    /// UTM medium
     UtmMedium,
+    /// UTM campaign
     UtmCampaign,
+    /// UTM content
     UtmContent,
+    /// UTM term
     UtmTerm,
+    /// Screen width bucket
     ScreenWidth,
+    /// Screen orientation
     Orientation,
 }
 
@@ -117,25 +155,63 @@ impl Display for Dimension {
     }
 }
 
+impl Dimension {
+    /// Return all report dimensions in dashboard order
+    pub const fn all() -> &'static [Self] {
+        &[
+            Self::Platform,
+            Self::Browser,
+            Self::Url,
+            Self::UrlEntry,
+            Self::UrlExit,
+            Self::Path,
+            Self::Mobile,
+            Self::Referrer,
+            Self::City,
+            Self::Country,
+            Self::Fqdn,
+            Self::UtmCampaign,
+            Self::UtmContent,
+            Self::UtmMedium,
+            Self::UtmSource,
+            Self::UtmTerm,
+            Self::ScreenWidth,
+            Self::Orientation,
+        ]
+    }
+}
+
+/// One point in a graph report
 #[derive(Serialize, Deserialize, JsonSchema, Debug, Clone)]
 #[serde(rename_all = "camelCase")]
 pub struct ReportGraphPoint {
+    /// Start timestamp of the graph bucket
     pub bin_start: DateTime<Utc>,
+    /// Metric value for the graph bucket
     pub value: f64,
 }
 
+/// Graph report points ordered by bucket start
 pub type ReportGraph = Vec<ReportGraphPoint>;
+
+/// Dimension table values mapped to their metric value
 pub type ReportTable = BTreeMap<String, f64>;
 
+/// Overall metric summary for a report range
 #[derive(Serialize, Deserialize, JsonSchema, Clone, Debug, Default)]
 #[serde(rename_all = "camelCase")]
 pub struct ReportStats {
+    /// Total pageviews
     pub total_views: u64,
+    /// Distinct visitor groups
     pub unique_visitors: u64,
+    /// Bounce rate, when session metrics are available
     pub bounce_rate: Option<f64>,
+    /// Average time on site, when session metrics are available
     pub avg_time_on_site: Option<f64>,
 }
 
+/// Filter applied to a dashboard report query
 #[derive(Serialize, Deserialize, JsonSchema, Debug, Clone, Hash, Eq, PartialEq, PartialOrd, Ord)]
 #[serde(rename_all = "camelCase")]
 pub struct DimensionFilter {