feat: implement alert configuration and event logging

- Added CRUD operations for alert configurations in the FeeRepository.
- Introduced AlertConfig and AlertEvent structs for managing alert data.
- Implemented methods to insert, list, update, and soft-delete alert configurations.
- Added logging functionality for alert events with relevant metrics.
- Created integration tests for alert configuration and event logging endpoints.
- Enhanced fee polling with metrics tracking for better observability.

Author: temiport25

.github/workflows/ci.yml

@@ -0,0 +1,124 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel in-progress runs for the same branch on new pushes.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # Job 1: check — fast-fail on formatting errors and clippy warnings.
+  # Runs first; if it fails the more expensive test/build jobs are skipped.
+  # ---------------------------------------------------------------------------
+  check:
+    name: Format & Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust (stable + rustfmt + clippy)
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      # Lightweight cache just for the registry index — no target/ needed here.
+      - name: Cache Cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+          key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-registry-
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+      - name: Run Clippy
+        run: cargo clippy --all-targets --all-features -- -D warnings
+        env:
+          STELLAR_NETWORK: testnet
+          POLL_INTERVAL_SECONDS: "60"
+          DATABASE_URL: "sqlite::memory:"
+
+  # ---------------------------------------------------------------------------
+  # Job 2: test — run the full test suite including integration tests.
+  # ---------------------------------------------------------------------------
+  test:
+    name: Test Suite
+    runs-on: ubuntu-latest
+    needs: check
+    env:
+      STELLAR_NETWORK: testnet
+      POLL_INTERVAL_SECONDS: "60"
+      DATABASE_URL: "sqlite::memory:"
+      RUST_LOG: error
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust (stable)
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Cargo artifacts
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-test-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-test-
+            ${{ runner.os }}-cargo-
+
+      - name: Install SQLite system library
+        run: sudo apt-get update && sudo apt-get install -y libsqlite3-dev
+
+      - name: Run all tests
+        run: cargo test --all
+
+  # ---------------------------------------------------------------------------
+  # Job 3: build — verify the release binary compiles cleanly.
+  # Runs in parallel with test; both depend on check passing first.
+  # ---------------------------------------------------------------------------
+  build:
+    name: Release Build
+    runs-on: ubuntu-latest
+    needs: check
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust (stable)
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Cargo artifacts
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-release-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-release-
+            ${{ runner.os }}-cargo-
+
+      - name: Install SQLite system library
+        run: sudo apt-get update && sudo apt-get install -y libsqlite3-dev
+
+      - name: Build release binary
+        run: cargo build --release
+        env:
+          STELLAR_NETWORK: testnet
+          POLL_INTERVAL_SECONDS: "60"
+          DATABASE_URL: "sqlite::memory:"

packages/core/Cargo.toml

@@ -7,6 +7,10 @@ edition = "2021"
 name = "stellar-fee-tracker"
 path = "src/main.rs"
 
+[lib]
+name = "stellar_fee_tracker"
+path = "src/lib.rs"
+
 [dependencies]
 # Web framework
 axum = { version = "0.7", features = ["json"] }
@@ -45,8 +49,13 @@ sqlx = { version = "0.7", features = ["sqlite", "runtime-tokio-native-tls", "mac
 # Async trait support (required for dyn-compatible async traits)
 async-trait = "0.1"
 
+# Metrics
+prometheus = "0.13"
+
 [dev-dependencies]
 tokio = { version = "1", features = ["full", "test-util"] }
 proptest = "1"
 tokio-test = "0.4"
-tower = "0.5"
+tower = { version = "0.5", features = ["util"] }
+http-body-util = "0.1"
+wiremock = "0.5"

packages/core/migrations/002_alert_configs.sql

@@ -0,0 +1,11 @@
+-- Migration 002: Alert configurations
+-- Stores webhook targets for outbound fee-spike notifications.
+
+CREATE TABLE IF NOT EXISTS alert_configs (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    webhook_url TEXT    NOT NULL,
+    threshold   TEXT    NOT NULL DEFAULT 'Major',
+    enabled     INTEGER NOT NULL DEFAULT 1,
+    created_at  TEXT    NOT NULL DEFAULT (datetime('now')),
+    updated_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+);

packages/core/migrations/003_alert_events.sql

@@ -0,0 +1,17 @@
+-- Migration 003: Alert events log
+-- Records every triggered alert dispatch for auditing and debugging.
+
+CREATE TABLE IF NOT EXISTS alert_events (
+    id           INTEGER PRIMARY KEY AUTOINCREMENT,
+    config_id    INTEGER REFERENCES alert_configs(id),
+    severity     TEXT    NOT NULL,
+    peak_fee     INTEGER NOT NULL,
+    baseline_fee REAL    NOT NULL,
+    spike_ratio  REAL    NOT NULL,
+    webhook_url  TEXT    NOT NULL,
+    delivered    INTEGER NOT NULL DEFAULT 0,  -- 1 = success, 0 = failed
+    triggered_at TEXT    NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_alert_events_triggered_at
+    ON alert_events (triggered_at);

packages/core/src/alerts/mod.rs

@@ -0,0 +1 @@
+pub mod webhook;

packages/core/src/alerts/webhook.rs

@@ -0,0 +1,92 @@
+//! Webhook alert delivery.
+//!
+//! Dispatches HTTP POST notifications to registered webhook targets when a
+//! fee spike is detected. Every delivery attempt — successful or not — is
+//! persisted in the `alert_events` table via [`FeeRepository::log_alert_event`].
+//!
+//! This module is the integration point for Issue #31 (webhook delivery) and
+//! Issue #32 (alert history). The `dispatch` function is called by the
+//! scheduler / insights engine whenever a spike crosses an alert threshold.
+
+use std::sync::Arc;
+
+use chrono::Utc;
+
+use crate::repository::{AlertEvent, FeeRepository};
+
+/// Payload describing a triggered fee-spike alert.
+#[derive(Debug, Clone)]
+pub struct AlertPayload {
+    /// The alert config row id that triggered this dispatch (if known).
+    pub config_id: Option<i64>,
+    /// Severity label, e.g. "Minor", "Major", "Critical".
+    pub severity: String,
+    /// Highest fee observed during the spike window (in stroops).
+    pub peak_fee: i64,
+    /// Rolling baseline fee used for comparison.
+    pub baseline_fee: f64,
+    /// `peak_fee / baseline_fee`.
+    pub spike_ratio: f64,
+    /// Destination webhook URL.
+    pub webhook_url: String,
+}
+
+/// Dispatch a webhook notification and log the outcome to the database.
+///
+/// The HTTP client (`reqwest`) is not yet wired up in this stub — the
+/// `delivered` flag defaults to `false` until Issue #31 lands and the full
+/// HTTP POST is implemented.  The repository logging is fully functional.
+pub async fn dispatch(payload: AlertPayload, repository: Arc<FeeRepository>) {
+    // TODO (Issue #31): perform the actual HTTP POST here and capture success.
+    let delivered = false;
+
+    let event = AlertEvent {
+        id: None,
+        config_id: payload.config_id,
+        severity: payload.severity.clone(),
+        peak_fee: payload.peak_fee,
+        baseline_fee: payload.baseline_fee,
+        spike_ratio: payload.spike_ratio,
+        webhook_url: payload.webhook_url.clone(),
+        delivered,
+        triggered_at: Utc::now().to_rfc3339(),
+    };
+
+    if let Err(err) = repository.log_alert_event(&event).await {
+        tracing::error!(
+            "Failed to log alert event for webhook {}: {}",
+            payload.webhook_url,
+            err
+        );
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::db::create_pool;
+
+    #[tokio::test]
+    async fn dispatch_logs_event_to_database() {
+        let pool = create_pool("sqlite::memory:").await.unwrap();
+        let repo = Arc::new(FeeRepository::new(pool));
+
+        let payload = AlertPayload {
+            config_id: None,
+            severity: "Major".to_string(),
+            peak_fee: 8000,
+            baseline_fee: 130.5,
+            spike_ratio: 61.3,
+            webhook_url: "https://hooks.example.com/test".to_string(),
+        };
+
+        dispatch(payload, repo.clone()).await;
+
+        let events = repo.query_alert_history(10, None, None).await.unwrap();
+        assert_eq!(events.len(), 1);
+        assert_eq!(events[0].severity, "Major");
+        assert_eq!(events[0].peak_fee, 8000);
+        // delivered = false until Issue #31 implements the HTTP POST
+        assert!(!events[0].delivered);
+    }
+}