feat(anomaly): AI-powered carbon emission anomaly detection (rebased on main, port fix) — supersedes #10

[kiro-agent]

This pull request was created by @kiro-agent on behalf of @D-source1602 👻

Comment with /kiro fix to address specific feedback or /kiro all to address everything.
_{Learn about Kiro autonomous agent}

---

Summary

Conflict-free version of PR #10 (anomaly detection by @anshikasharma3332). Original PR's branch was based on an old main (only PR #5 merged), so its diff against current main showed a 2300-line "deletion" of PRs #6, #7, and #9 as a side-effect.

This PR rebases the work cleanly: only the additive changes (203 lines), original authorship preserved.

Action needed: merge this PR, then close PR #10.

What this ships

A working AI anomaly detection feature, end-to-end.

Backend

• backend/src/routes/anomaly.routes.ts — pure stats detector
  • Rolling z-score over a window of 5 readings
  • Sudden-percentage-increase rule (≥40%)
  • Severity grading: low / medium / high based on z-score + pct
  • Stateless POST /api/v1/anomaly/detect — accepts { readings: [{ timestamp, co2 }, ...] }
  • Returns { hasAnomaly, alerts: [...], summary }
  • Architecture mirrors what a future FastAPI + Isolation Forest microservice would expose; swapping in real ML later is contained to the detect() function body
• backend/src/routes/index.ts — anomaly router mounted alongside /auth, /aqi, /reports (consistent with the established pattern, not a parallel app.use in app.ts)

Frontend

• src/lib/anomaly.ts — typed wrapper using the shared api() helper (so it picks up VITE_API_URL automatically)
• src/App.tsx — adds RUN SPIKE SCAN button on the AI Anomaly Detection capability card on the Dashboard, with a severity-colored result panel that shows alert details on detection or a green "no spike" badge otherwise

Bug fix vs. original PR #10

The original frontend code hard-coded:

fetch('http://localhost:5000/api/v1/anomaly/detect', ...)

But the backend listens on port 4000. The feature would have failed 100% of the time in a demo. This PR uses the shared api() helper which reads VITE_API_URL from .env.

Conflict resolution strategy

Rather than carrying 2300 lines of "deletion noise" forward, I:

1. Reset the branch to current main (which has PRs feat(auth): Phase 3 — JWT auth controller, RBAC middleware, admin seed #5–feat(reports): PDF report generator (rebased on main, conflict-free) — supersedes #8 #9 merged)
2. Re-applied only the 4 additive changes
3. Preserved Anshika's authorship via git -c user.name="Anshika Sharma" -c user.email="anshikasharma3332@gmail.com" commit

git log -1 on this commit shows the original author/committer.

To run after merging

git checkout main && git pull origin main
cd backend
npm install
npm run dev

# in another terminal
cd CLIMATRIX
npm run dev

Open http://localhost:5173 → log in → on the Dashboard's Capabilities section, click RUN SPIKE SCAN on the AI Anomaly Detection card. The mock 5-reading series ends with a 260 µg/m³ spike — you should see a red alert panel with severity HIGH and a confidence score.

Smoke test directly with curl:

curl -X POST http://localhost:4000/api/v1/anomaly/detect \
  -H 'Content-Type: application/json' \
  -d '{"readings":[
    {"timestamp":"2026-01-01T10:00:00Z","co2":120},
    {"timestamp":"2026-01-01T11:00:00Z","co2":125},
    {"timestamp":"2026-01-01T12:00:00Z","co2":260}
  ]}'

Should return hasAnomaly: true with one alert.

Diff stat

4 files, +203 / 0.