⚡ Bolt: Optimized Blockchain Integrity and Admin Stats

.jules/bolt.md

@@ -45,3 +45,11 @@
 ## 2026-02-10 - Group-By for Multi-Count Statistics
 **Learning:** Executing multiple `count()` queries with different filters (e.g., for different statuses) causes redundant database scans and network round-trips.
 **Action:** Use a single SQL `GROUP BY` query to fetch counts for all categories/statuses at once, then process the results in Python.
+
+## 2026-02-11 - O(1) Blockchain Verification
+**Learning:** Verifying the integrity of a blockchain-style chain by querying the database for the previous record's hash on every check is inefficient and adds unnecessary latency.
+**Action:** Store the `previous_integrity_hash` directly in the record during creation. This enables O(1) single-record integrity checks without additional database lookups. Use a thread-safe cache to keep the most recent hash in memory to further optimize the creation path.
+
+## 2026-02-11 - Multi-Metric Aggregate Queries
+**Learning:** Executing multiple separate `count()` queries to gather system statistics results in multiple database round-trips and redundant table scans.
+**Action:** Use a single SQLAlchemy query with `func.count()` and `func.sum(case(...))` to calculate all metrics in one go. This reduces network overhead and allows the database to perform calculations in a single pass.

backend/init_db.py

@@ -95,6 +95,9 @@ def index_exists(table, index_name):
                 if not index_exists("issues", "ix_issues_user_email"):
                     conn.execute(text("CREATE INDEX IF NOT EXISTS ix_issues_user_email ON issues (user_email)"))
 
+                if not index_exists("issues", "ix_issues_previous_integrity_hash"):
+                    conn.execute(text("CREATE INDEX IF NOT EXISTS ix_issues_previous_integrity_hash ON issues (previous_integrity_hash)"))
+
                 # Voice and Language Support Columns (Issue #291)
                 if not column_exists("issues", "submission_type"):
                     conn.execute(text("ALTER TABLE issues ADD COLUMN submission_type VARCHAR DEFAULT 'text'"))

backend/models.py

@@ -149,6 +149,7 @@ class Issue(Base):
     location = Column(String, nullable=True)
     action_plan = Column(JSON, nullable=True)
     integrity_hash = Column(String, nullable=True)  # Blockchain integrity seal
+    previous_integrity_hash = Column(String, nullable=True, index=True) # Linked hash for O(1) verification
 
     # Voice and Language Support (Issue #291)
     submission_type = Column(String, default="text")  # 'text', 'voice'

backend/routers/admin.py

@@ -1,5 +1,6 @@
 from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy.orm import Session
+from sqlalchemy import func, case
 from typing import List
 
 from backend.database import get_db
@@ -20,11 +21,19 @@ def get_users(skip: int = 0, limit: int = 100, db: Session = Depends(get_db)):
 
 @router.get("/stats")
 def get_system_stats(db: Session = Depends(get_db)):
-    total_users = db.query(User).count()
-    admin_users = db.query(User).filter(User.role == UserRole.ADMIN).count()
+    """
+    Get system-wide user statistics.
+    Optimized: Uses a single aggregate query to calculate multiple metrics simultaneously,
+    reducing database round-trips and scan overhead.
+    """
+    stats = db.query(
+        func.count(User.id).label("total"),
+        func.sum(case((User.role == UserRole.ADMIN, 1), else_=0)).label("admins"),
+        func.sum(case((User.is_active.is_(True), 1), else_=0)).label("active")
+    ).first()
 
     return {
-        "total_users": total_users,
-        "admin_count": admin_users,
-        "active_users": db.query(User).filter(User.is_active == True).count(),
+        "total_users": stats.total or 0,
+        "admin_count": int(stats.admins or 0),
+        "active_users": int(stats.active or 0),
     }

backend/routers/issues.py

@@ -30,7 +30,7 @@
     send_status_notification
 )
 from backend.spatial_utils import get_bounding_box, find_nearby_issues
-from backend.cache import recent_issues_cache, nearby_issues_cache
+from backend.cache import recent_issues_cache, nearby_issues_cache, blockchain_last_hash_cache
 from backend.hf_api_service import verify_resolution_vqa
 from backend.dependencies import get_http_client
 from backend.rag_service import rag_service
@@ -172,16 +172,23 @@ async def create_issue(
         # Save to DB only if no nearby issues found or deduplication failed
         if deduplication_info is None or not deduplication_info.has_nearby_issues:
             # Blockchain feature: calculate integrity hash for the report
-            # Optimization: Fetch only the last hash to maintain the chain with minimal overhead
-            prev_issue = await run_in_threadpool(
-                lambda: db.query(Issue.integrity_hash).order_by(Issue.id.desc()).first()
-            )
-            prev_hash = prev_issue[0] if prev_issue and prev_issue[0] else ""
+            # Performance Boost: Use thread-safe cache to eliminate DB query for last hash
+            prev_hash = blockchain_last_hash_cache.get("last_hash")
+            if prev_hash is None:
+                # Cache miss: Fetch only the last hash from DB
+                prev_issue = await run_in_threadpool(
+                    lambda: db.query(Issue.integrity_hash).order_by(Issue.id.desc()).first()
+                )
+                prev_hash = prev_issue[0] if prev_issue and prev_issue[0] else ""
+                blockchain_last_hash_cache.set(data=prev_hash, key="last_hash")
 
-# Simple but effective SHA-256 chaining
+            # Simple but effective SHA-256 chaining
             hash_content = f"{description}|{category}|{prev_hash}"
             integrity_hash = hashlib.sha256(hash_content.encode()).hexdigest()
 
+            # Update cache for next report
+            blockchain_last_hash_cache.set(data=integrity_hash, key="last_hash")
+
             # RAG Retrieval (New)
             relevant_rule = rag_service.retrieve(description)
             initial_action_plan = None
@@ -199,7 +206,8 @@ async def create_issue(
                 longitude=longitude,
                 location=location,
                 action_plan=initial_action_plan,
-                integrity_hash=integrity_hash
+                integrity_hash=integrity_hash,
+                previous_integrity_hash=prev_hash
             )
 
             # Offload blocking DB operations to threadpool
@@ -620,24 +628,32 @@ def get_user_issues(
 async def verify_blockchain_integrity(issue_id: int, db: Session = Depends(get_db)):
     """
     Verify the cryptographic integrity of a report using the blockchain-style chaining.
-    Optimized: Uses column projection to fetch only needed data.
+    Optimized: Uses previous_integrity_hash column for O(1) verification.
     """
-    # Fetch current issue data
+    # Fetch current issue data including the link to previous hash
+    # Performance Boost: Use projected previous_integrity_hash to avoid N+1 or secondary lookups
     current_issue = await run_in_threadpool(
         lambda: db.query(
-            Issue.id, Issue.description, Issue.category, Issue.integrity_hash
+            Issue.id,
+            Issue.description,
+            Issue.category,
+            Issue.integrity_hash,
+            Issue.previous_integrity_hash
         ).filter(Issue.id == issue_id).first()
     )
 
     if not current_issue:
         raise HTTPException(status_code=404, detail="Issue not found")
 
-    # Fetch previous issue's integrity hash to verify the chain
-    prev_issue_hash = await run_in_threadpool(
-        lambda: db.query(Issue.integrity_hash).filter(Issue.id < issue_id).order_by(Issue.id.desc()).first()
-    )
+    # Determine previous hash (use stored link or fallback for legacy records)
+    prev_hash = current_issue.previous_integrity_hash
 
-    prev_hash = prev_issue_hash[0] if prev_issue_hash and prev_issue_hash[0] else ""
+    if prev_hash is None:
+        # Fallback for legacy records created before O(1) optimization
+        prev_issue_hash = await run_in_threadpool(
+            lambda: db.query(Issue.integrity_hash).filter(Issue.id < issue_id).order_by(Issue.id.desc()).first()
+        )
+        prev_hash = prev_issue_hash[0] if prev_issue_hash and prev_issue_hash[0] else ""
 
     # Recompute hash based on current data and previous hash
     # Chaining logic: hash(description|category|prev_hash)