feat: document and test daily civic intelligence refinement engine

frontend/netlify.toml

@@ -0,0 +1,2 @@
+[build]
+  publish = "dist"

frontend/public/_headers

@@ -0,0 +1,5 @@
+/*
+  X-Frame-Options: DENY
+  X-Content-Type-Options: nosniff
+  X-XSS-Protection: 1; mode=block
+  Referrer-Policy: strict-origin-when-cross-origin

frontend/public/_redirects

@@ -0,0 +1 @@
+/* /index.html 200

netlify.toml

@@ -11,18 +11,3 @@
 
 # Environment variables (set these in Netlify dashboard)
 # VITE_API_URL = https://your-backend.onrender.com
-
-# Redirects for SPA
-[[redirects]]
-  from = "/*"
-  to = "/index.html"
-  status = 200
-
-# Headers for security
-[[headers]]
-  for = "/*"
-  [headers.values]
-    X-Frame-Options = "DENY"
-    X-Content-Type-Options = "nosniff"
-    X-XSS-Protection = "1; mode=block"
-    Referrer-Policy = "strict-origin-when-cross-origin"

package.json

@@ -23,13 +23,13 @@
     "sqlite3": "^5.1.7"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.12",
+    "@types/jest": "^29.5.14",
     "@types/node": "^20.11.24",
     "@types/node-cron": "^3.0.11",
     "@types/sqlite3": "^3.1.11",
     "jest": "^29.7.0",
-    "jest-util": "^30.2.0",
-    "ts-jest": "^29.1.2",
+    "jest-util": "^30.3.0",
+    "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
     "typescript": "^5.3.3"
   }

scheduler/dailyRefinementJob.ts

@@ -10,6 +10,19 @@ import { Issue } from "../services/types";
 const dbPath =
   process.env.DB_PATH || path.join(__dirname, "../../backend/app.db");
 
+/**
+ * DailyRefinementJob: Orchestrates the daily process of trend detection,
+ * adaptive weight optimization, and index generation. Runs locally with SQLite.
+ *
+ * Algorithm and Evolution Logic:
+ * 1. Executes every 24 hours via node-cron.
+ * 2. Fetches all civic issues reported in the past 24 hours.
+ * 3. Uses TrendAnalyzer to find the top 5 emerging keywords and category spikes (>50% increase).
+ * 4. Uses AdaptiveWeights to increase severity multipliers for critical issue patterns
+ *    and dynamically tighten/relax the global duplicate threshold based on volume.
+ * 5. Calculates a Daily Civic Intelligence Index using IntelligenceIndex, heavily weighting resolutions.
+ * 6. Stores these insights locally for auditability without external APIs.
+ */
 export class DailyRefinementJob {
   private db: sqlite3.Database;
   private trendAnalyzer: TrendAnalyzer;

services/adaptiveWeights.ts

@@ -2,6 +2,19 @@ import { Issue, ModelWeights } from "./types";
 import * as fs from "fs";
 import * as path from "path";
 
+/**
+ * AdaptiveWeights: Dynamically tunes category priorities based on historical
+ * critical assignments, storing previous states for full auditability.
+ *
+ * Algorithm and Evolution Logic:
+ * If a particular category (like "Pothole" or "Flooding") is frequently marked Critical manually
+ * or resolved (> 5 times), this engine increases the internal category weight by +0.5,
+ * capping at 10 to auto-prioritize it going forward.
+ * It also intelligently manipulates the Duplicate Pattern detection threshold:
+ * Tightening (+0.01 to 0.95 max) when platform usage > 100, and relaxing (-0.01 to 0.70 min)
+ * on slower days to adaptively manage noise filtering.
+ * Saves an explicit snapshot history within modelWeights.json for complete AI model audibility.
+ */
 export class AdaptiveWeights {
   private configPath: string;
 

services/intelligenceIndex.ts

@@ -2,6 +2,17 @@ import { Issue, DailySnapshot } from "./types";
 import * as fs from "fs";
 import * as path from "path";
 
+/**
+ * IntelligenceIndex: Produces a daily Civic Intelligence snapshot, aggregating
+ * system performance metrics to capture overall municipal health and activity.
+ *
+ * Algorithm and Evolution Logic:
+ * Starts at a 50.0 Index Baseline.
+ * Increases (+): Base score raises by ratio of resolved civic issues (high resolutions = better performance).
+ * Minor Bonus (+): If top keywords contain rich descriptions, minor bump (+0.5 per keyword).
+ * Penalizes (-): Immediate penalty per significant Category Spikes (-1.5 per concern) to represent unmet issues.
+ * Stores a JSON snapshot daily (e.g. data/dailySnapshots/YYYY-MM-DD.json) comparing delta changes.
+ */
 export class IntelligenceIndex {
   private snapshotsDir: string;
 

services/priorityEngine.ts

@@ -295,6 +295,17 @@ const CATEGORIES: Record<string, string[]> = {
   Environment: ["tree", "cutting", "deforestation", "forest", "nature"],
 };
 
+/**
+ * PriorityEngine: Analyzes issues to assign a severity and urgency score,
+ * leveraging adaptive weights for continuously optimized dynamic routing.
+ *
+ * Algorithm and Evolution Logic:
+ * Uses pre-defined keyword dictionaries across Critical, High, Medium, and Low severity tiers.
+ * It scores issues using substring matches. Critically, it multiplies the base score by dynamic
+ * parameters managed by AdaptiveWeights.
+ * If `modelWeights.json` determines that "Pothole" incidents are currently severe,
+ * the multiplier > 1 upgrades the severity automatically, representing self-improving infrastructure.
+ */
 export class PriorityEngine {
   private adaptiveWeights: AdaptiveWeights;
   private lastWeightsCheck: number = 0;

services/trendAnalyzer.ts

@@ -1,5 +1,16 @@
 import { Issue } from "./types";
 
+/**
+ * TrendAnalyzer: Performs local pattern detection, finding emerging keywords,
+ * significant category volume spikes, and geographical clustering of issues.
+ *
+ * Algorithm and Evolution Logic:
+ * 1. Trend detection extracts the top 5 most common keywords (>= 3 chars) after filtering stop-words.
+ * 2. It compares the last 24h category distribution with the previous 24h.
+ *    If an issue spikes > 50% and exceeds a baseline of 5, it's flagged as an "Emerging Concern".
+ * 3. Uses rounded coordinate boundaries (approx. 1.1km) to locate geographical clusters
+ *    and determine the region with the highest concentration of issues.
+ */
 export class TrendAnalyzer {
   public getTopKeywords(issues: Issue[], limit: number = 5): string[] {
     const wordCounts: Record<string, number> = {};

tests/dailyRefinement.test.ts

@@ -162,6 +162,14 @@ describe("Daily Civic Intelligence Refinement Engine Tests", () => {
       }
     });
 
+    test("should handle empty issue lists gracefully", () => {
+      const snapshot = intelligenceIndex.generateIndex([], [], []);
+      expect(snapshot.indexScore).toBe(50.0);
+      expect(snapshot.delta).toBe(0.0);
+      expect(snapshot.emergingConcerns).toHaveLength(0);
+      expect(snapshot.topKeywords).toHaveLength(0);
+    });
+
     test("should generate and save daily snapshot score", () => {
       const snapshot = intelligenceIndex.generateIndex(
         dummyIssues,

tests/priorityEngine.test.ts

@@ -85,4 +85,14 @@ describe('PriorityEngine Tests', () => {
     const result = priorityEngine.calculateSeverityAndUrgency('Huge pothole on the road', 'Pothole');
     expect(result.suggestedCategories).toContain('Pothole');
   });
+
+  test('should handle empty descriptions or descriptions with no keywords gracefully', () => {
+    const result = priorityEngine.calculateSeverityAndUrgency('Normal everyday thing', 'Other');
+
+    // No matching severity keyword implies default score of 10
+    expect(result.severityScore).toBe(10);
+    expect(result.severity).toBe('Low');
+    expect(result.urgencyScore).toBe(10);
+    expect(result.reasoning).toContain('Classified as Low Severity (maintenance/cosmetic issue)');
+  });
 });