Anomaly Detection System

A high-performance, real-time anomaly detection backend system built with Spring Boot 4.0.1, WebFlux, and GraalVM Native Image for instant startup and minimal memory footprint.

🚀 Features

• Reactive Data Ingestion: Non-blocking data processing using Spring WebFlux
• Real-time Anomaly Detection: Multiple hypothesis-based detection algorithms running in parallel
• Webhook Notifications: Asynchronous alerts when anomalies are detected
• GraalVM Native Image: Sub-second startup time and reduced memory consumption
• Observation/Monitoring Ready: Actuator endpoints for monitoring and health checks

🛠️ Tech Stack

• Java 25 - Latest JDK with modern language features
• Spring Boot 4.0.1 - Latest Spring framework with enhanced reactive support
• Spring WebFlux - Reactive web framework for non-blocking operations
• Project Reactor - Reactive programming foundation
• GraalVM Native Image - AOT compilation for native executables
• Maven - Build and dependency management

📋 Prerequisites

• Java 25 or higher
• Maven 3.9+
• Docker (for containerized deployment)
• GraalVM 25 (for native builds)

---

🤝 Contributing & Feedback

We would love hearing from you! Whether you've found a glitch or have a grand idea, your input helps improve this project.

• 🐛 Report a Bug: Found something broken? Open an issue so we can fix it.
• 💡 Feature Requests: Have an idea for a new feature? We’d love to hear it!
• 🔧 Pull Requests: Want to contribute code? PRs are always welcome.
• 💬 General Feedback: Any bug, issue, or suggestion is most welcome.

---

🏗️ Building the Application

Standard JAR Build

mvn clean package

🐳 Docker Image Build

docker build -t anomaly-native .

Run Container

docker run \
  --name anomaly-app \
  -p 8080:8080 \
  -p 8081:8081 \
  --memory="128m" \
  --memory-swap="128m" \
  --cpus="2.0" \
  --restart=unless-stopped \
  anomaly-native

📡 API Endpoints

Data Ingestion

POST /api/v1/ingest/sample
Content-Type: application/json

{
  "source": "sensor-001",
  "timestamp": 1706227200000,
  "value": 42.5
}

Webhook Registration

POST /api/v1/webhooks
Content-Type: application/json

{
  "source": "sensor-001",
  "url": "https://your-webhook.com/alerts",
  "name": "Production Alerts",
  "metadata": {}
}

Health Check

Please note that management endpoints exposed on port 8081

GET /actuator/health

🧪 Testing

The project includes comprehensive test coverage:

# Run all tests
mvn test

Test stack includes:

• JUnit 5
• Reactor Test
• WireMock (for webhook testing)
• Awaitility (for async assertions)

📊 Architecture

┌─────────────┐
│   Client    │
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────────┐
│     WebFlux Ingestion Layer         │
│  (Non-blocking request handling)    │
└──────┬──────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────┐
│   Parallel Hypothesis Processing    │
│  ┌────────┐ ┌────────┐ ┌────────┐   │
│  │ Drift  │ │ Spike  │ │ Regime │   │
│  └────────┘ └────────┘ └────────┘   │
└──────┬──────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────┐
│      Aggregation & Decision         │
└──────┬──────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────┐
│   Async Webhook Notification        │
│    (Bounded Elastic Scheduler)      │
└─────────────────────────────────────┘

🎯 Key Implementation Highlights

Reactive Pipeline

• Parallel Processing: Multiple anomaly detection algorithms run concurrently
• Backpressure Handling: Automatic flow control prevents system overload
• Non-blocking I/O: Efficient resource utilization

Scheduler Optimization

• CPU-bound tasks: Schedulers.parallel() for hypothesis calculations
• I/O-bound tasks: Schedulers.boundedElastic() for webhook notifications

Native Image Optimization

• Custom reflection configuration for runtime efficiency
• Resource bundling for application properties
• No-fallback mode for pure native execution

📈 Performance Characteristics

Metric	JVM Mode	Native Mode
Startup Time	~3-5s	<100ms
Memory (RSS)	~250MB	~80MB

🔧 Configuration

Detection Hypothesis Tuning

The system uses three parallel detection algorithms, each with configurable sensitivity:

1. Spike Detection (Fast Anomalies)

spike:
  detector:
    type: adaptive-zscore
    alpha: 0.08              # Learning rate (higher = faster adaptation)
    min-samples: 30          # Minimum data points before detection
    z-threshold: 3.5         # Sensitivity (lower = more sensitive)
    variance-floor: 1e-6     # Minimum variance to prevent division by zero
  decision:
    type: bayesian
    prior-probability: 0.01  # Expected anomaly rate (1%)
    decision-threshold: 0.90 # Confidence required (90%)

Use Case: Detect sudden, short-lived spikes (sensor glitches, traffic bursts) Tuning: Decrease z-threshold to 2.5-3.0 for more sensitive detection

2. Drift Detection (Gradual Changes)

drift:
  detector:
    type: adaptive-zscore
    alpha: 0.01              # Slower learning (detects sustained shifts)
    min-samples: 50          # More samples for stable baseline
    z-threshold: 2.0         # Lower threshold (drift is subtler)
    variance-floor: 1e-5
  decision:
    type: evidence
    decay: 0.9               # Evidence decay rate
    threshold: 21.0          # Accumulated evidence required

Use Case: Detect gradual baseline shifts (degrading sensors, trend changes) Tuning: Increase min-samples to 100 for more stable drift detection

3. Regime Change (Structural Shifts)

regime_change:
  detector:
    type: cusum               # Cumulative Sum control chart
    ewma-alpha: 0.05         # Exponential smoothing factor
    drift: 0.5               # Allowable drift magnitude
    threshold: 5.0           # CUSUM threshold
    min-samples: 20
  decision:
    type: evidence
    decay: 0.9
    threshold: 21.0

Use Case: Detect system state changes (mode switches, operational phases) Tuning: Lower threshold to 3.0-4.0 for earlier regime change detection

Global Settings

anomaly:
  processor:
    timeout-millis: 250      # Max processing time per sample
  aggregator:
    threshold: 0.8           # 80% hypotheses must agree for alert

webhook:
  notification:
    enabled: true            # Toggle webhook notifications
  storage:
    type: memory             # In-memory webhook config storage

⚠️ Note: Webhook configurations are stored in-memory only and will be lost on application restart. Persistent storage (RDS/PostgreSQL) support is planned for future releases.

Quick Tuning Guide

Scenario	Adjustment	Impact
Too many false positives	Increase z-threshold (3.5 → 4.0)	Less sensitive
Missing real anomalies	Decrease z-threshold (3.5 → 2.5)	More sensitive
Noisy data	Increase min-samples (30 → 50)	More stable baseline
Fast-changing baseline	Increase alpha (0.08 → 0.15)	Faster adaptation
Require unanimous agreement	Increase aggregator.threshold (0.8 → 1.0)	Fewer alerts

📝 License

This is a portfolio project demonstrating modern Java/Spring capabilities.

Built to showcase:

• Advanced reactive programming patterns
• GraalVM native compilation
• Production-ready Spring Boot architecture
• Modern Java 25 features

---

Note: This is a demonstration project highlighting enterprise-grade reactive systems and cloud-native deployment patterns.