Implement SSE-based real-time alert streaming system

.env

@@ -0,0 +1,19 @@
+# ── Eagle Environment Configuration ──────────────────────────────────────
+# Copy this file to .env and fill in the values before running the project.
+
+# Redis (used for temporal memory ring buffer)
+REDIS_URL=redis://localhost:6379/0
+
+# Ollama (local VLM inference)
+OLLAMA_HOST=http://localhost:11434
+
+# Detection
+YOLO_MODEL=yolov8n.pt
+DETECTION_CONFIDENCE=0.4
+
+# Policy
+POLICY_PATH=policies/default.yaml
+
+# Backend
+API_HOST=0.0.0.0
+API_PORT=8000

apps/backend/core/queue.py

@@ -0,0 +1,3 @@
+import asyncio
+
+alert_queue = asyncio.Queue()

apps/backend/core/redis.py

@@ -0,0 +1,7 @@
+import redis.asyncio as redis
+
+redis_client = redis.Redis(
+    host="localhost",
+    port=6379,
+    decode_responses=True
+)

apps/backend/main.py

@@ -5,7 +5,10 @@
 from fastapi.responses import Response
 from prometheus_client import generate_latest
 
-from libs.observability.metrics import frames_processed_total
+# from libs.observability.metrics import frames_processed_total
+
+from apps.backend.routes.alerts import router as alert_router
+
 
 app = FastAPI()
 
@@ -36,3 +39,5 @@ def health():
 @app.get("/metrics")
 async def metrics():
     return Response(generate_latest(), media_type="text/plain")
+
+app.include_router(alert_router)

apps/backend/routes/alerts.py

@@ -0,0 +1,68 @@
+import asyncio
+import uuid
+from datetime import datetime
+
+from fastapi import APIRouter, Request
+from fastapi.responses import StreamingResponse
+
+from apps.backend.core.redis import redis_client
+from libs.schemas.alert import Alert
+from apps.backend.services.alert_broker import publish_alert
+from apps.backend.core.queue import alert_queue
+
+router = APIRouter()
+
+CHANNEL_NAME = "eagle_alerts"
+
+
+# =========================
+# SSE STREAM ENDPOINT
+# =========================
+@router.get("/alerts/stream")
+async def stream_alerts(request: Request):
+
+    async def event_generator():
+
+        print("✅ SSE CONNECTED")
+
+        while True:
+
+            if await request.is_disconnected():
+                break
+
+            try:
+                alert = await asyncio.wait_for(alert_queue.get(), timeout=10)
+
+                yield f"data: {alert}\n\n"
+
+            except asyncio.TimeoutError:
+                yield ": keepalive\n\n"
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive"
+        }
+    )
+# =========================
+# TEST ALERT ENDPOINT
+# =========================
+@router.post("/alerts/test")
+async def test_alert():
+
+    alert = Alert(
+        id=str(uuid.uuid4()),
+        camera_id="cam_01",
+        track_id=7,
+        label="Suspicious",
+        confidence=0.92,
+        reason="Repeated loitering near restricted exit",
+        timestamp=datetime.utcnow(),
+        zone="Exit A"
+    )
+
+    await publish_alert(alert)
+
+    return {"status": "sent"}

apps/backend/services/alert_broker.py

@@ -0,0 +1,16 @@
+import json
+from apps.backend.core.redis import redis_client
+from apps.backend.core.queue import alert_queue
+
+CHANNEL_NAME = "eagle_alerts"
+
+
+async def publish_alert(alert):
+
+    await redis_client.publish(
+        "eagle_alerts",
+        alert.model_dump_json()
+    )
+
+    # 🔥 ALSO push to SSE queue
+    await alert_queue.put(alert.model_dump_json())

apps/frontend/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

apps/frontend/AGENTS.md

@@ -0,0 +1,5 @@
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->

apps/frontend/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

apps/frontend/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

apps/frontend/app/globals.css

@@ -0,0 +1,26 @@
+@import "tailwindcss";
+
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+  }
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: Arial, Helvetica, sans-serif;
+}

apps/frontend/app/layout.tsx

@@ -0,0 +1,33 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: "Create Next App",
+  description: "Generated by create next app",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html
+      lang="en"
+      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
+    >
+      <body className="min-h-full flex flex-col">{children}</body>
+    </html>
+  );
+}

apps/frontend/app/page.tsx

@@ -0,0 +1,12 @@
+"use client";
+
+import AlertPanel from "@/components/AlertPanel";
+
+export default function Home() {
+  return (
+    <main style={{ padding: "20px" }}>
+      <h1>Eagle Surveillance System 🦅</h1>
+      <AlertPanel />
+    </main>
+  );
+}

apps/frontend/components/AlertPanel.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+type Alert = {
+  id?: string;
+  label: string;
+  reason: string;
+  confidence: number;
+};
+
+export default function AlertPanel() {
+  const [alerts, setAlerts] = useState<Alert[]>([]);
+  const [status, setStatus] = useState("connecting");
+
+  useEffect(() => {
+    const eventSource = new EventSource(
+      "http://localhost:8000/alerts/stream"
+    );
+
+    // ✅ connection opened
+    eventSource.onopen = () => {
+      console.log("SSE connected");
+      setStatus("connected");
+    };
+
+    // ✅ receiving messages
+    eventSource.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+
+        setAlerts((prev) => [data, ...prev]);
+      } catch (err) {
+        console.log("Invalid SSE data:", event.data);
+      }
+    };
+
+    // ❌ error handler (IMPORTANT FIXED)
+    eventSource.onerror = () => {
+      console.log("SSE error - retrying automatically...");
+      setStatus("reconnecting");
+    };
+
+    return () => {
+      eventSource.close();
+    };
+  }, []);
+
+  return (
+    <div style={{ padding: "20px" }}>
+      <h2>🦅 Live Alerts</h2>
+
+      <p>Status: {status}</p>
+
+      {alerts.length === 0 ? (
+        <p>No alerts yet...</p>
+      ) : (
+        alerts.map((alert, index) => (
+          <div
+            key={alert.id || index}
+            style={{
+              border: "1px solid #ddd",
+              padding: "10px",
+              marginBottom: "10px",
+            }}
+          >
+            <h3>{alert.label}</h3>
+            <p>{alert.reason}</p>
+            <small>Confidence: {alert.confidence}</small>
+          </div>
+        ))
+      )}
+    </div>
+  );
+}