heavy add-ons: 13+ features implemented

backend/engine.py

@@ -7,6 +7,9 @@ import numpy as np
 import cv2
 from collections import defaultdict
 from constants import MODEL_CLASSES
+from tracker_config import get_tracker_path
+from speed import estimate_speeds
+from pcu import compute_pcu
 
 
 def _side(p, a, b):
@@ -139,6 +142,7 @@ def run(model, video_path, line, config, on_frame, save_annotated=False, annotat
     flow_times = []
     conf_scores = []
     heatmap_points = []
+    track_positions = defaultdict(list)
     raw_events = [["frame_index", "timestamp_sec", "vehicle_id", "class_name", "direction"]]
 
     start = time.time()
@@ -148,7 +152,7 @@ def run(model, video_path, line, config, on_frame, save_annotated=False, annotat
     # ExecuTorch: https://docs.ultralytics.com/integrations/executorch/#what-are-the-system-requirements-for-executorch-export
     results = model.track(
         source=video_path,
-        tracker="bytetrack.yaml",
+        tracker=get_tracker_path(),
         imgsz=736,    # MUST match OpenVINO export imgsz — compiled graph is fixed shape
         conf=config.get("conf", 0.12),
         iou=config.get("iou", 0.6),
@@ -194,6 +198,7 @@ def run(model, video_path, line, config, on_frame, save_annotated=False, annotat
                 cy = int((box[1] + box[3]) / 2)
 
                 heatmap_points.append([cx, cy])
+                track_positions[obj_id].append((frame_idx, cx, cy))
 
                 current = _side((cx, cy), a, b)
 
@@ -253,6 +258,12 @@ def run(model, video_path, line, config, on_frame, save_annotated=False, annotat
     actual_fps = round(total / processing_time, 2) if processing_time > 0 else 0
     speed_vs_rt = round(actual_fps / fps, 2) if fps > 0 else 0
 
+    speed_data = estimate_speeds(dict(track_positions))
+    pcu_data = compute_pcu(
+        {str(k): v for k, v in class_in.items()},
+        {str(k): v for k, v in class_out.items()},
+    )
+
     result = {
         "class_in": dict(class_in),
         "class_out": dict(class_out),
@@ -264,6 +275,8 @@ def run(model, video_path, line, config, on_frame, save_annotated=False, annotat
         "processing_time": processing_time,
         "actual_fps": actual_fps,
         "speed_vs_realtime": speed_vs_rt,
+        "speed": speed_data,
+        "pcu": pcu_data,
     }
 
     if annotated_path and os.path.exists(annotated_path):

backend/export_json.py

@@ -0,0 +1,85 @@
+"""
+Structured JSON artifact export with complete run metadata.
+
+Produces a self-contained JSON document suitable for programmatic
+consumption, API integration, and archival.
+"""
+import json
+import os
+from datetime import datetime, timezone
+
+
+def export_json(data, video_meta, engine_config, out_dir):
+    """Generate a comprehensive JSON export of the analysis run.
+
+    Args:
+        data: Engine result dict (counts, congestion, events, etc.)
+        video_meta: dict with filename, fps, frames, duration, resolution, pixels
+        engine_config: dict with imgsz, conf, iou, stride, etc.
+        out_dir: Output directory path
+
+    Returns:
+        Filename string or None
+    """
+    class_in = data.get("class_in", {})
+    class_out = data.get("class_out", {})
+    congestion = data.get("congestion", [])
+    raw_events = data.get("raw_events", [])
+    pcu_data = data.get("pcu", {})
+    speed_data = data.get("speed", {})
+
+    # Build events list from raw_events (skip header row)
+    events = []
+    for row in raw_events[1:]:
+        events.append({
+            "frame": row[0],
+            "timestamp_sec": row[1],
+            "vehicle_id": row[2],
+            "class_name": row[3],
+            "direction": row[4],
+        })
+
+    total_in = sum(class_in.values())
+    total_out = sum(class_out.values())
+
+    doc = {
+        "urbanflow_version": "1.1",
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "video": video_meta,
+        "engine": {
+            "model": "VehicleNet-Y26s (OpenVINO INT8)",
+            "imgsz": engine_config.get("imgsz", 736),
+            "conf": engine_config.get("conf", 0.12),
+            "iou": engine_config.get("iou", 0.6),
+            "stride": engine_config.get("detect_stride", 2),
+            "tracker": "ByteTrack (custom)",
+            "batch": 2,
+        },
+        "performance": {
+            "processing_time_sec": data.get("processing_time", 0),
+            "actual_fps": data.get("actual_fps", 0),
+            "speed_vs_realtime": data.get("speed_vs_realtime", 0),
+        },
+        "counts": {
+            "total_in": total_in,
+            "total_out": total_out,
+            "total": total_in + total_out,
+            "per_class_in": {str(k): v for k, v in class_in.items()},
+            "per_class_out": {str(k): v for k, v in class_out.items()},
+        },
+        "pcu": pcu_data,
+        "speed_distribution": speed_data.get("distribution", {}),
+        "congestion": {
+            "peak": max(congestion) if congestion else 0,
+            "average": round(sum(congestion) / len(congestion), 1) if congestion else 0,
+            "timeline": congestion,
+        },
+        "flow_times": data.get("flow_times", []),
+        "events": events,
+    }
+
+    path = os.path.join(out_dir, "analysis.json")
+    with open(path, "w") as f:
+        json.dump(doc, f, indent=2, default=str)
+
+    return "analysis.json"

backend/pcu.py

@@ -0,0 +1,67 @@
+"""
+Passenger Car Unit (PCU) conversion using IRC:106-1990 guidelines.
+
+PCU normalizes heterogeneous Indian traffic into a single unit of measurement
+used by transport authorities for capacity analysis and road design.
+"""
+from constants import MODEL_CLASSES
+
+# IRC:106-1990 PCU equivalency factors
+_PCU_TABLE = {
+    0: 1.0,   # Hatchback
+    1: 1.0,   # Sedan
+    2: 1.0,   # SUV
+    3: 1.0,   # MUV
+    4: 3.0,   # Bus
+    5: 3.0,   # Truck
+    6: 1.2,   # Three-wheeler (Auto-rickshaw)
+    7: 0.5,   # Two-wheeler
+    8: 3.0,   # LCV
+    9: 3.0,   # Mini-bus
+    10: 3.0,  # Tempo-traveller
+    11: 0.5,  # Bicycle
+    12: 1.0,  # Van
+    13: 1.0,  # Others
+}
+
+
+def get_pcu_factor(class_id):
+    return _PCU_TABLE.get(class_id, 1.0)
+
+
+def compute_pcu(class_in, class_out):
+    """Convert raw vehicle counts to PCU values.
+
+    Args:
+        class_in: dict {class_id_str: count}
+        class_out: dict {class_id_str: count}
+
+    Returns:
+        dict with total_pcu, pcu_in, pcu_out, per_class breakdown
+    """
+    pcu_in = 0.0
+    pcu_out = 0.0
+    per_class = {}
+
+    all_ids = set(list(class_in.keys()) + list(class_out.keys()))
+    for cid_str in all_ids:
+        cid = int(cid_str)
+        factor = get_pcu_factor(cid)
+        in_count = class_in.get(cid_str, 0)
+        out_count = class_out.get(cid_str, 0)
+        cls_pcu_in = round(in_count * factor, 1)
+        cls_pcu_out = round(out_count * factor, 1)
+        pcu_in += cls_pcu_in
+        pcu_out += cls_pcu_out
+        per_class[MODEL_CLASSES.get(cid, f"cls_{cid}")] = {
+            "count": in_count + out_count,
+            "factor": factor,
+            "pcu": round(cls_pcu_in + cls_pcu_out, 1),
+        }
+
+    return {
+        "total_pcu": round(pcu_in + pcu_out, 1),
+        "pcu_in": round(pcu_in, 1),
+        "pcu_out": round(pcu_out, 1),
+        "per_class": per_class,
+    }

backend/server.py

@@ -135,6 +135,10 @@ def get_report(video_id: str, name: str):
         media = "application/pdf"
     elif name.endswith(".mp4"):
         media = "video/mp4"
+    elif name.endswith(".json"):
+        media = "application/json"
+    elif name.endswith(".csv"):
+        media = "text/csv"
 
     return FileResponse(str(path), media_type=media)
 
@@ -180,6 +184,23 @@ def download_all_reports(video_id: str):
         return Response(content=str(e), status_code=500)
 
 
+FEEDBACK_PATH = Path(tempfile.gettempdir()) / "urbanflow_feedback.json"
+
+
+@app.post("/api/feedback")
+async def submit_feedback(request_data: dict = None):
+    from datetime import datetime, timezone
+    feedback = request_data or {}
+    entries = []
+    if FEEDBACK_PATH.exists():
+        entries = json.loads(FEEDBACK_PATH.read_text())
+    feedback["timestamp"] = datetime.now(timezone.utc).isoformat()
+    entries.append(feedback)
+    FEEDBACK_PATH.write_text(json.dumps(entries, indent=2))
+    print(f"[BACKEND] Feedback received: {feedback.get('type', 'general')}")
+    return {"status": "ok"}
+
+
 @app.websocket("/ws/run")
 async def ws_run(ws: WebSocket):
     await ws.accept()
@@ -223,6 +244,15 @@ async def ws_run(ws: WebSocket):
         result = task.result()  # re-raises any exception from the engine
         result["report_format"] = report_format
         result["video_path"] = path
+        result["video_meta"] = {
+            "filename": video_info.get(video_id, "unknown"),
+            "fps": cfg.get("video_fps", 0),
+            "frames": cfg.get("frames", 0),
+            "duration": cfg.get("duration", 0),
+            "resolution": cfg.get("resolution", [0, 0]),
+            "pixels": cfg.get("pixels", 0),
+        }
+        result["engine_config"] = cfg
         run_results[video_id] = result
         await ws.send_text(json.dumps({
             "done": True,
@@ -230,6 +260,8 @@ async def ws_run(ws: WebSocket):
             "processing_time": result["processing_time"],
             "actual_fps": result["actual_fps"],
             "speed_vs_realtime": result["speed_vs_realtime"],
+            "pcu": result.get("pcu", {}),
+            "speed_distribution": result.get("speed", {}).get("distribution", {}),
         }))
         await ws.close()
 

backend/speed.py

@@ -0,0 +1,62 @@
+"""
+Lightweight speed estimation using pixel displacement between frames.
+
+No camera calibration required — classifies vehicles into relative
+speed categories (Slow/Normal/Fast) based on percentile ranking
+of pixel-per-frame displacement within the video.
+"""
+import numpy as np
+
+
+def estimate_speeds(track_positions):
+    """Compute per-track speed category from centroid displacement history.
+
+    Args:
+        track_positions: dict {track_id: [(frame_idx, cx, cy), ...]}
+
+    Returns:
+        dict with per_track speeds and aggregate distribution
+    """
+    displacements = {}
+
+    for tid, positions in track_positions.items():
+        if len(positions) < 2:
+            continue
+        positions.sort(key=lambda x: x[0])
+        total_disp = 0.0
+        count = 0
+        for i in range(1, len(positions)):
+            dx = positions[i][1] - positions[i - 1][1]
+            dy = positions[i][2] - positions[i - 1][2]
+            total_disp += np.sqrt(dx * dx + dy * dy)
+            count += 1
+        displacements[tid] = total_disp / count if count > 0 else 0.0
+
+    if not displacements:
+        return {"per_track": {}, "distribution": {"slow": 0, "normal": 0, "fast": 0}}
+
+    speeds = np.array(list(displacements.values()))
+    p33 = np.percentile(speeds, 33)
+    p66 = np.percentile(speeds, 66)
+
+    per_track = {}
+    counts = {"slow": 0, "normal": 0, "fast": 0}
+
+    for tid, spd in displacements.items():
+        if spd <= p33:
+            cat = "slow"
+        elif spd <= p66:
+            cat = "normal"
+        else:
+            cat = "fast"
+        per_track[int(tid)] = {"px_per_frame": round(spd, 1), "category": cat}
+        counts[cat] += 1
+
+    total = sum(counts.values())
+    distribution = {
+        "slow": round(counts["slow"] / total * 100, 1) if total else 0,
+        "normal": round(counts["normal"] / total * 100, 1) if total else 0,
+        "fast": round(counts["fast"] / total * 100, 1) if total else 0,
+    }
+
+    return {"per_track": per_track, "distribution": distribution}

backend/tracker_config.py

@@ -0,0 +1,35 @@
+"""
+Custom ByteTrack configuration optimized for Indian traffic conditions.
+
+Tuning rationale (vs Ultralytics defaults):
+- Lower thresholds: Indian roads have heavy occlusion (autos behind buses)
+- Higher track_buffer: Vehicles disappear behind large vehicles for longer
+- Looser match_thresh: Apparent shape changes during partial occlusion
+
+Reference: https://docs.ultralytics.com/modes/track/
+"""
+import os
+import tempfile
+
+_YAML_CONTENT = """# UrbanFlow — ByteTrack config for Indian heterogeneous traffic
+# Base: https://github.com/ultralytics/ultralytics/blob/main/ultralytics/cfg/trackers/bytetrack.yaml
+
+tracker_type: bytetrack
+track_high_thresh: 0.20
+track_low_thresh: 0.08
+new_track_thresh: 0.20
+track_buffer: 45
+match_thresh: 0.75
+fuse_score: true
+"""
+
+_CONFIG_PATH = os.path.join(tempfile.gettempdir(), "urbanflow_bytetrack.yaml")
+
+
+def get_tracker_path():
+    """Write custom YAML once and return its path."""
+    if not os.path.exists(_CONFIG_PATH):
+        with open(_CONFIG_PATH, "w") as f:
+            f.write(_YAML_CONTENT)
+        print(f"[tracker] Custom ByteTrack config written: {_CONFIG_PATH}")
+    return _CONFIG_PATH

backend/visualize.py

@@ -6,6 +6,7 @@ import matplotlib
 matplotlib.use("Agg")
 import matplotlib.pyplot as plt
 from matplotlib.ticker import MaxNLocator
+from export_json import export_json
 
 # Formal MIS palette
 C_PRIMARY = "#1e293b"
@@ -244,6 +245,12 @@ def generate_all(data, model_classes, out_dir, report_format="png"):
         lambda: confidence_dist(data.get("conf_scores", []), out_dir, fmt),
         lambda: spatial_heatmap(heatmap_points, video_path, out_dir, fmt),
         lambda: export_csv(raw_events, out_dir),
+        lambda: export_json(
+            data,
+            data.get("video_meta", {}),
+            data.get("engine_config", {}),
+            out_dir,
+        ),
     ]:
         name = fn()
         if name:

frontend/initial.html

@@ -80,6 +80,32 @@
             background-color: var(--cocoa) !important;
             color: var(--t1) !important;
         }
+
+        /* Onboarding */
+        .onboard-overlay {
+            position: fixed; inset: 0; z-index: 9999;
+            background: rgba(0,0,0,0.92);
+            display: flex; align-items: center; justify-content: center;
+        }
+        .onboard-card {
+            background: #0a0a0a; border: 1px solid #2a2a2a;
+            border-radius: 16px; max-width: 440px; width: 90%;
+            padding: 40px 32px; text-align: center;
+        }
+        .onboard-step { display: none; }
+        .onboard-step.active { display: block; }
+        .onboard-dots { display: flex; gap: 6px; justify-content: center; margin-top: 20px; }
+        .onboard-dot {
+            width: 8px; height: 8px; border-radius: 50%;
+            background: #333; transition: background 0.2s;
+        }
+        .onboard-dot.active { background: var(--cocoa-l); }
+
+        /* Mobile responsive */
+        @media (max-width: 768px) {
+            main { grid-template-columns: 1fr !important; padding: 16px !important; }
+            h1 { font-size: 2.2rem !important; }
+        }
     </style>
 </head>
 
@@ -378,6 +404,53 @@
             window.location.href = '/';
         }
     </script>
+
+    <!-- Onboarding Walkthrough -->
+    <div id="onboard-overlay" class="onboard-overlay" style="display:none">
+        <div class="onboard-card">
+            <div class="onboard-step active" data-step="0">
+                <i class="fa-solid fa-cloud-arrow-up text-4xl mb-4" style="color:var(--cocoa-l)"></i>
+                <h3 class="text-lg font-bold mb-2" style="color:#f0ece6">Upload a Traffic Video</h3>
+                <p class="text-xs" style="color:#777;line-height:1.7">Drag & drop or select a video file recorded from any traffic camera. MP4, MOV, AVI formats supported.</p>
+            </div>
+            <div class="onboard-step" data-step="1">
+                <i class="fa-solid fa-draw-polygon text-4xl mb-4" style="color:var(--cocoa-l)"></i>
+                <h3 class="text-lg font-bold mb-2" style="color:#f0ece6">Draw a Counting Boundary</h3>
+                <p class="text-xs" style="color:#777;line-height:1.7">Click two points on the first frame to define a spatial boundary. Vehicles crossing this line will be counted and classified.</p>
+            </div>
+            <div class="onboard-step" data-step="2">
+                <i class="fa-solid fa-chart-line text-4xl mb-4" style="color:var(--cocoa-l)"></i>
+                <h3 class="text-lg font-bold mb-2" style="color:#f0ece6">Review Analytics & Export</h3>
+                <p class="text-xs" style="color:#777;line-height:1.7">Watch real-time charts populate as inference runs. Download annotated video, reports, and structured JSON when complete.</p>
+            </div>
+            <div class="onboard-dots">
+                <span class="onboard-dot active"></span>
+                <span class="onboard-dot"></span>
+                <span class="onboard-dot"></span>
+            </div>
+            <div class="flex gap-3 justify-center mt-6">
+                <button onclick="closeOnboarding()" class="text-[10px] font-bold uppercase tracking-widest px-4 py-2 rounded-full" style="color:#555;border:1px solid #222">Skip</button>
+                <button id="onboard-next" onclick="nextOnboardStep()" class="text-[10px] font-bold uppercase tracking-widest px-6 py-2 rounded-full" style="background:var(--cocoa);color:#f0ece6">Next</button>
+            </div>
+        </div>
+    </div>
+    <script>
+        let _obStep = 0;
+        function nextOnboardStep() {
+            _obStep++;
+            if (_obStep >= 3) { closeOnboarding(); return; }
+            document.querySelectorAll('.onboard-step').forEach((s, i) => s.classList.toggle('active', i === _obStep));
+            document.querySelectorAll('.onboard-dot').forEach((d, i) => d.classList.toggle('active', i === _obStep));
+            if (_obStep === 2) document.getElementById('onboard-next').innerText = 'Get Started';
+        }
+        function closeOnboarding() {
+            document.getElementById('onboard-overlay').style.display = 'none';
+            localStorage.setItem('uf_onboarded', '1');
+        }
+        if (!localStorage.getItem('uf_onboarded')) {
+            document.getElementById('onboard-overlay').style.display = 'flex';
+        }
+    </script>
 </body>
 
 </html>

frontend/vehicles.html

@@ -325,6 +325,101 @@
             padding-top: 0;
             border-top: none;
         }
+
+        /* Toast Notifications */
+        #toast-container {
+            position: fixed;
+            bottom: 20px;
+            right: 20px;
+            z-index: 10000;
+            display: flex;
+            flex-direction: column;
+            gap: 8px;
+            pointer-events: none;
+        }
+        .toast {
+            background: #111;
+            border: 1px solid #2a2a2a;
+            color: #f0ece6;
+            font-size: 11px;
+            font-weight: 600;
+            padding: 10px 18px;
+            border-radius: 10px;
+            display: flex;
+            align-items: center;
+            gap: 8px;
+            pointer-events: auto;
+            animation: toastIn 0.3s ease-out;
+            max-width: 320px;
+        }
+        .toast.toast-out { animation: toastOut 0.3s ease-in forwards; }
+        .toast-success { border-color: #166534; }
+        .toast-success i { color: #22c55e; }
+        .toast-error { border-color: #7f1d1d; }
+        .toast-error i { color: #ef4444; }
+        .toast-info i { color: var(--cocoa-l); }
+        @keyframes toastIn { from { opacity: 0; transform: translateX(40px); } to { opacity: 1; transform: translateX(0); } }
+        @keyframes toastOut { from { opacity: 1; } to { opacity: 0; transform: translateX(40px); } }
+
+        /* Stats Empty State */
+        .stats-empty-overlay {
+            position: absolute;
+            inset: 0;
+            z-index: 10;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            background: rgba(0,0,0,0.7);
+            border-radius: 12px;
+        }
+
+        /* Mobile Responsive */
+        @media (max-width: 1024px) {
+            aside.w-60 { display: none; }
+            .mobile-nav { display: flex !important; }
+            #tab-overview { grid-template-columns: repeat(1, 1fr) !important; }
+            #tab-overview > div { grid-column: span 1 !important; }
+        }
+        @media (max-width: 768px) {
+            .grid-cols-3 { grid-template-columns: 1fr !important; }
+            .grid-cols-2 { grid-template-columns: 1fr !important; }
+            main { padding: 8px !important; }
+        }
+
+        /* Feedback form */
+        .fb-textarea {
+            background: #111;
+            border: 1px solid #2a2a2a;
+            border-radius: 8px;
+            color: #f0ece6;
+            font-size: 12px;
+            padding: 12px;
+            width: 100%;
+            min-height: 120px;
+            resize: vertical;
+            font-family: 'Inter', sans-serif;
+        }
+        .fb-textarea:focus { outline: none; border-color: var(--cocoa-l); }
+        .fb-select {
+            background: #111;
+            border: 1px solid #2a2a2a;
+            border-radius: 8px;
+            color: #f0ece6;
+            font-size: 11px;
+            padding: 8px 12px;
+            width: 100%;
+            font-family: 'Inter', sans-serif;
+        }
+        .fb-select:focus { outline: none; border-color: var(--cocoa-l); }
+        .fb-stars { display: flex; gap: 6px; }
+        .fb-star {
+            font-size: 22px;
+            color: #333;
+            cursor: pointer;
+            transition: color 0.15s;
+        }
+        .fb-star.active, .fb-star:hover { color: var(--cocoa-l); }
     </style>
 </head>
 
@@ -356,6 +451,10 @@
                 class="flex items-center px-4 py-2.5 rounded-lg transition cursor-pointer nav-item-inactive">
                 <i class="fa-solid fa-sliders w-6"></i> <span class="font-medium">Settings</span>
             </a>
+            <a onclick="switchTab('feedback')" id="nav-feedback"
+                class="flex items-center px-4 py-2.5 rounded-lg transition cursor-pointer nav-item-inactive">
+                <i class="fa-solid fa-comment-dots w-6"></i> <span class="font-medium">Feedback</span>
+            </a>
         </nav>
         <div class="mt-auto border-t p-4 flex flex-col items-center gap-2 bg-black flex-shrink-0"
             style="border-color:#2a2a2a">
@@ -368,9 +467,26 @@
                 style="color:#a89f97" onmouseover="this.style.color='#c89a6c'"
                 onmouseout="this.style.color='#a89f97'">Terms &amp; Conditions</button>
             <p class="text-[9px] mt-1" style="color:#333">&#169; 2026 UrbanFlow</p>
+            <p class="text-[8px] mt-0.5" style="color:#222" title="Keyboard shortcuts: 1-6 switch tabs, D downloads artifacts">⌨ Press 1-6 for tabs, D for download</p>
         </div>
     </aside>
 
+    <!-- Mobile Navigation (hidden on desktop) -->
+    <div class="mobile-nav hidden fixed top-0 left-0 right-0 z-30 bg-black border-b border-slate-800 px-2 py-1.5 items-center justify-between">
+        <img src="uf_rf.png" alt="UF" class="h-8">
+        <div class="flex gap-1">
+            <button onclick="switchTab('about')" class="text-[9px] px-2 py-1 rounded" style="color:#a89f97"><i class="fa-solid fa-circle-info"></i></button>
+            <button onclick="switchTab('overview')" class="text-[9px] px-2 py-1 rounded" style="color:#a89f97"><i class="fa-solid fa-desktop"></i></button>
+            <button onclick="switchTab('run-details')" class="text-[9px] px-2 py-1 rounded" style="color:#a89f97"><i class="fa-solid fa-microchip"></i></button>
+            <button onclick="switchTab('reports')" class="text-[9px] px-2 py-1 rounded" style="color:#a89f97"><i class="fa-solid fa-file-lines"></i></button>
+            <button onclick="switchTab('settings')" class="text-[9px] px-2 py-1 rounded" style="color:#a89f97"><i class="fa-solid fa-sliders"></i></button>
+            <button onclick="switchTab('feedback')" class="text-[9px] px-2 py-1 rounded" style="color:#a89f97"><i class="fa-solid fa-comment-dots"></i></button>
+        </div>
+    </div>
+
+    <!-- Toast Container -->
+    <div id="toast-container"></div>
+
     <main class="flex-1 flex flex-col h-full min-w-0 p-4 gap-4">
 
         <!-- TAB: About -->
@@ -515,7 +631,14 @@
         </div>
 
         <!-- TAB: Overview -->
-        <div id="tab-overview" class="hidden grid grid-cols-12 gap-4 flex-1 min-h-0 overflow-hidden">
+        <div id="tab-overview" class="hidden grid grid-cols-12 gap-4 flex-1 min-h-0 overflow-hidden" style="position:relative">
+
+            <!-- Empty State Overlay -->
+            <div id="stats-empty-state" class="stats-empty-overlay">
+                <i class="fa-solid fa-chart-column text-4xl mb-4" style="color:#333"></i>
+                <span class="text-sm font-bold" style="color:#555">Processing not started</span>
+                <span class="text-[11px] mt-1" style="color:#444">Charts will populate in real-time once analysis begins</span>
+            </div>
 
             <!-- Congestion Index -->
             <div
@@ -545,6 +668,13 @@
                     <div class="absolute inset-0 flex flex-col items-center justify-center pointer-events-none">
                         <span class="text-3xl font-black text-slate-900" id="cnt-total">0</span>
                         <span class="text-[10px] font-bold text-slate-400 uppercase tracking-wider">Total Units</span>
+                        <span class="text-[9px] font-bold mt-0.5 uppercase tracking-wider flex items-center gap-1" style="color:#8b5e3c">
+                            <span id="cnt-pcu">0</span> PCU
+                            <span class="info-wrap" style="margin-left:2px">
+                                <span class="info-btn" style="width:11px;height:11px;font-size:6px"><i class="fa-solid fa-info"></i></span>
+                                <span class="info-tip">Passenger Car Units (IRC:106-1990). Normalizes mixed traffic into a single unit for capacity analysis.</span>
+                            </span>
+                        </span>
                     </div>
                 </div>
             </div>
@@ -655,6 +785,32 @@
                     </div>
                 </div>
 
+                <!-- Insights Panel (xAI) -->
+                <div id="insights-panel" class="hidden">
+                    <div class="grid grid-cols-2 gap-6 mt-6">
+                        <div class="bg-white rounded-xl border border-slate-200 shadow-sm flex flex-col overflow-hidden">
+                            <div class="px-6 py-4 border-b border-slate-100 bg-slate-50/50">
+                                <h3 class="font-bold text-slate-800 text-sm flex items-center">Speed Distribution
+                                    <span class="info-wrap"><span class="info-btn"><i class="fa-solid fa-info"></i></span>
+                                        <span class="info-tip">Relative speed categories based on pixel displacement. Slow/Normal/Fast are percentile-based within this video.</span></span>
+                                </h3>
+                            </div>
+                            <div class="p-6" id="speed-dist-content">
+                                <div class="flex gap-4 items-end justify-center h-32" id="speed-bars"></div>
+                            </div>
+                        </div>
+                        <div class="bg-white rounded-xl border border-slate-200 shadow-sm flex flex-col overflow-hidden">
+                            <div class="px-6 py-4 border-b border-slate-100 bg-slate-50/50">
+                                <h3 class="font-bold text-slate-800 text-sm flex items-center">Congestion Insights
+                                    <span class="info-wrap"><span class="info-btn"><i class="fa-solid fa-info"></i></span>
+                                        <span class="info-tip">Automated peak detection and congestion classification.</span></span>
+                                </h3>
+                            </div>
+                            <div class="p-6 space-y-3" id="congestion-insights"></div>
+                        </div>
+                    </div>
+                </div>
+
             </div>
         </div>
 
@@ -852,6 +1008,54 @@
             </div>
         </div>
 
+        <!-- TAB: Feedback -->
+        <div id="tab-feedback" class="hidden flex-1 min-h-0 overflow-y-auto" style="padding:16px">
+            <div class="max-w-2xl mx-auto">
+                <div class="bg-black border border-slate-800 rounded-xl p-8 shadow-2xl space-y-6">
+                    <div class="text-center">
+                        <h2 class="text-xl font-bold" style="color:#f0ece6">Share Your Feedback</h2>
+                        <p class="text-xs mt-2" style="color:#777">We're in the requirements-gathering phase. Your input directly shapes what gets built.</p>
+                    </div>
+
+                    <div class="space-y-4">
+                        <div>
+                            <label class="text-[10px] font-bold uppercase tracking-widest block mb-2" style="color:#a89f97">Overall Experience</label>
+                            <div class="fb-stars" id="fb-stars">
+                                <span class="fb-star" data-v="1" onclick="setRating(1)">&#9733;</span>
+                                <span class="fb-star" data-v="2" onclick="setRating(2)">&#9733;</span>
+                                <span class="fb-star" data-v="3" onclick="setRating(3)">&#9733;</span>
+                                <span class="fb-star" data-v="4" onclick="setRating(4)">&#9733;</span>
+                                <span class="fb-star" data-v="5" onclick="setRating(5)">&#9733;</span>
+                            </div>
+                        </div>
+
+                        <div>
+                            <label class="text-[10px] font-bold uppercase tracking-widest block mb-2" style="color:#a89f97">Category</label>
+                            <select class="fb-select" id="fb-type">
+                                <option value="general">General Feedback</option>
+                                <option value="bug">Bug Report</option>
+                                <option value="feature">Feature Request</option>
+                                <option value="accuracy">Detection Accuracy</option>
+                                <option value="ux">User Experience</option>
+                            </select>
+                        </div>
+
+                        <div>
+                            <label class="text-[10px] font-bold uppercase tracking-widest block mb-2" style="color:#a89f97">Details</label>
+                            <textarea class="fb-textarea" id="fb-text" placeholder="Tell us what worked, what didn't, or what you'd like to see..."></textarea>
+                        </div>
+
+                        <button onclick="submitFeedback()" class="w-full py-3 font-bold text-sm rounded-full transition hover:scale-[1.02] active:scale-95"
+                            style="background:#0a0a0a;border:1px solid var(--cocoa);color:var(--cocoa-l)">
+                            Submit Feedback <i class="fa-solid fa-paper-plane ml-2 text-[10px]"></i>
+                        </button>
+                    </div>
+
+                    <p class="text-[10px] text-center" style="color:#444">Or email us directly at <strong style="color:#c89a6c">support@urbanflow.in</strong></p>
+                </div>
+            </div>
+        </div>
+
     </main>
 
     <script>
@@ -934,7 +1138,7 @@
 
         // =========== Tab switching ===========
         function switchTab(tab) {
-            ['about', 'overview', 'run-details', 'reports', 'settings'].forEach(t => {
+            ['about', 'overview', 'run-details', 'reports', 'settings', 'feedback'].forEach(t => {
                 const el = document.getElementById('tab-' + t);
                 const nav = document.getElementById('nav-' + t);
                 if (el) el.classList.toggle('hidden', tab !== t);
@@ -950,6 +1154,96 @@
             });
         }
 
+        // =========== Toast System ===========
+        function showToast(message, type) {
+            type = type || 'info';
+            const icons = { success: 'fa-check-circle', error: 'fa-circle-xmark', info: 'fa-circle-info' };
+            const el = document.createElement('div');
+            el.className = `toast toast-${type}`;
+            el.innerHTML = `<i class="fa-solid ${icons[type] || icons.info}"></i> ${message}`;
+            document.getElementById('toast-container').appendChild(el);
+            setTimeout(() => { el.classList.add('toast-out'); setTimeout(() => el.remove(), 300); }, 3000);
+        }
+
+        // =========== Keyboard Shortcuts ===========
+        const TAB_KEYS = { '1': 'about', '2': 'overview', '3': 'run-details', '4': 'reports', '5': 'settings', '6': 'feedback' };
+        document.addEventListener('keydown', function(e) {
+            if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA' || e.target.tagName === 'SELECT') return;
+            if (TAB_KEYS[e.key]) { switchTab(TAB_KEYS[e.key]); return; }
+            if (e.key === 'd' || e.key === 'D') {
+                const vid = document.body.dataset.lastVideoId;
+                if (vid) {
+                    window.open(`/bundle/${vid}`, '_blank');
+                    showToast('Download started', 'success');
+                }
+            }
+        });
+
+        // =========== Feedback ===========
+        let _fbRating = 0;
+        function setRating(n) {
+            _fbRating = n;
+            document.querySelectorAll('.fb-star').forEach(s => {
+                s.classList.toggle('active', parseInt(s.dataset.v) <= n);
+            });
+        }
+        async function submitFeedback() {
+            const type = document.getElementById('fb-type').value;
+            const text = document.getElementById('fb-text').value.trim();
+            if (!text && !_fbRating) { showToast('Please add a rating or comment', 'error'); return; }
+            const res = await fetch('/api/feedback', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ rating: _fbRating, type, text })
+            });
+            if (res.ok) {
+                showToast('Thank you for your feedback!', 'success');
+                document.getElementById('fb-text').value = '';
+                setRating(0);
+            } else {
+                showToast('Failed to submit — please try again', 'error');
+            }
+        }
+
+        // =========== PCU Calculation (client-side mirror) ===========
+        const PCU_TABLE = {0:1,1:1,2:1,3:1,4:3,5:3,6:1.2,7:0.5,8:3,9:3,10:3,11:0.5,12:1,13:1};
+        function calcPCU(classIn, classOut) {
+            let total = 0;
+            for (const [k, v] of Object.entries(classIn)) total += (PCU_TABLE[parseInt(k)] || 1) * v;
+            for (const [k, v] of Object.entries(classOut)) total += (PCU_TABLE[parseInt(k)] || 1) * v;
+            return Math.round(total * 10) / 10;
+        }
+
+        // =========== Insights Rendering ===========
+        function renderInsights(d) {
+            const panel = document.getElementById('insights-panel');
+            panel.classList.remove('hidden');
+
+            // Speed distribution bars
+            const dist = d.speed_distribution || {};
+            const bars = document.getElementById('speed-bars');
+            const colors = { slow: '#ef4444', normal: '#eab308', fast: '#22c55e' };
+            const labels = { slow: 'Slow', normal: 'Normal', fast: 'Fast' };
+            bars.innerHTML = ['slow', 'normal', 'fast'].map(cat => {
+                const pct = dist[cat] || 0;
+                const h = Math.max(8, pct * 1.2);
+                return `<div class="flex flex-col items-center gap-1">
+                    <span class="text-[10px] font-bold" style="color:${colors[cat]}">${pct}%</span>
+                    <div style="width:36px;height:${h}px;background:${colors[cat]};border-radius:6px;transition:height 0.5s"></div>
+                    <span class="text-[9px] font-bold text-slate-500 uppercase">${labels[cat]}</span>
+                </div>`;
+            }).join('');
+
+            // Congestion insights
+            const ci = document.getElementById('congestion-insights');
+            const pcu = d.pcu || {};
+            ci.innerHTML = [
+                infoRow('Total PCU', pcu.total_pcu || 0, 'Passenger Car Units (IRC:106-1990). Normalizes mixed traffic.'),
+                infoRow('PCU In / Out', `${pcu.pcu_in || 0} / ${pcu.pcu_out || 0}`, 'Directional PCU split.'),
+                infoRow('Speed Profile', `${dist.slow || 0}% slow · ${dist.normal || 0}% normal · ${dist.fast || 0}% fast`, 'Relative speed categories within this video.'),
+            ].join('');
+        }
+
         // =========== Run Details helpers ===========
         function detailRow(label, value, extra) {
             extra = extra || '';
@@ -1430,6 +1724,7 @@
             ws.onerror = e => {
                 console.error('WS Error:', e);
                 document.getElementById('proc-label').innerText = 'Connection Error';
+                showToast('Connection error — server may be busy', 'error');
                 if (badge) {
                     badge.innerText = 'Pipeline Failed';
                     badge.className = 'px-2.5 py-1 bg-red-900/40 text-red-100 text-[10px] font-bold rounded-full uppercase tracking-tighter';
@@ -1465,7 +1760,9 @@
             ws.onmessage = e => {
                 const d = JSON.parse(e.data);
 
-                // Backend engine error — surface it clearly
+                // Hide empty state on first data
+                const emptyState = document.getElementById('stats-empty-state');
+                if (emptyState) emptyState.style.display = 'none';
                 if (d.error) {
                     processingDone = true;
                     document.getElementById('proc-label').innerText = 'Engine Error';
@@ -1540,6 +1837,13 @@
                     const newWrap = document.getElementById('new-analysis-wrap');
                     if (newWrap) newWrap.classList.remove('hidden');
 
+                    // Toast + Insights
+                    showToast('Processing complete — artifacts ready', 'success');
+                    renderInsights(d);
+
+                    // Store video_id for keyboard shortcut download
+                    document.body.setAttribute('data-last-video-id', d.video_id);
+
                     return;
                 }
 
@@ -1559,6 +1863,11 @@
                 const currTotal = parseInt(cntTotalEl.innerText) || 0;
                 animateValue(cntTotalEl, currTotal, totalIn + totalOut, 300);
 
+                // Update PCU display
+                const pcuVal = calcPCU(d.class_in, d.class_out);
+                const pcuEl = document.getElementById('cnt-pcu');
+                if (pcuEl) pcuEl.innerText = pcuVal;
+
                 // Update doughnut
                 doughChart.data.datasets[0].data = [totalIn, totalOut];
                 doughChart.update();
@@ -1588,7 +1897,8 @@
             'annotated.mp4': { title: 'Annotated Video Export', desc: 'Rendered video with tracking overlays' },
             'heatmap.png': { title: 'Spatial Density Heatmap', desc: 'Aggregated path utilization mapping' },
             'heatmap.pdf': { title: 'Spatial Density Heatmap', desc: 'Aggregated path utilization mapping' },
-            'raw_data.csv': { title: 'Raw Analytics Export', desc: 'Comma-separated values of all crossings' }
+            'raw_data.csv': { title: 'Raw Analytics Export', desc: 'Comma-separated values of all crossings' },
+            'analysis.json': { title: 'Structured JSON Export', desc: 'Complete analysis data with metadata for API consumption' }
         };
 
         async function loadReports(videoId) {
@@ -1629,6 +1939,12 @@
                             <i class="fa-solid fa-file-csv text-6xl mb-4 text-white"></i>
                             <span class="text-xs font-bold uppercase tracking-widest text-slate-500">Raw Analytics Export</span>
                         </div>`;
+                } else if (name.endsWith('.json')) {
+                    previewHTML = `
+                        <div class="flex flex-col items-center justify-center py-12 text-slate-700">
+                            <i class="fa-solid fa-code text-6xl mb-4 text-white"></i>
+                            <span class="text-xs font-bold uppercase tracking-widest text-slate-500">Structured JSON</span>
+                        </div>`;
                 } else {
                     previewHTML = `<img src="${url}" alt="${info.title}" class="max-w-full max-h-[320px] object-contain rounded">`;
                 }