feat: database indexing optimization for financial queries (#128)

packages/backend/app/__init__.py

@@ -2,6 +2,7 @@
 from .config import Settings
 from .extensions import db, jwt
 from .routes import register_routes
+from .db.index_report import register_index_cli
 from .observability import (
     Observability,
     configure_logging,
@@ -51,6 +52,7 @@ def create_app(settings: Settings | None = None) -> Flask:
     # Redis (already global)
     # Blueprint routes
     register_routes(app)
+    register_index_cli(app)
 
     # Backward-compatible schema patch for existing databases.
     with app.app_context():

packages/backend/app/db/index_report.py

@@ -0,0 +1,91 @@
+"""
+Database index report utility (Issue #128).
+
+Run with: flask index-report
+
+Reports: current indexes, missing recommended indexes, table sizes.
+Helps track index health in production.
+"""
+
+from __future__ import annotations
+
+import click
+from flask import Flask
+from flask.cli import with_appcontext
+
+from ..extensions import db
+
+# Expected indexes — checked at startup in dev/test to catch regressions
+REQUIRED_INDEXES = [
+    "idx_expenses_user_spent_at",
+    "idx_expenses_user_category",
+    "idx_expenses_user_type_date",
+    "idx_expenses_user_month",
+    "idx_bills_user_due",
+    "idx_bills_user_active_due",
+    "idx_reminders_due",
+    "idx_reminders_pending_dispatch",
+    "idx_recurring_expenses_user_start",
+    "idx_recurring_expenses_active",
+    "idx_categories_user_name",
+    "idx_audit_logs_user_created",
+    "idx_audit_logs_action_created",
+]
+
+
+def get_existing_indexes(engine) -> list[str]:
+    """Query pg_indexes for all FinMind indexes."""
+    if engine.dialect.name != "postgresql":
+        return []
+    with engine.connect() as conn:
+        result = conn.execute(
+            db.text(
+                """
+                SELECT indexname FROM pg_indexes
+                WHERE schemaname = 'public'
+                ORDER BY indexname
+                """
+            )
+        )
+        return [row[0] for row in result]
+
+
+def check_missing_indexes(engine) -> list[str]:
+    """Return list of recommended indexes not yet present."""
+    existing = set(get_existing_indexes(engine))
+    return [idx for idx in REQUIRED_INDEXES if idx not in existing]
+
+
+def register_index_cli(app: Flask) -> None:
+    """Register the flask index-report CLI command."""
+
+    @app.cli.command("index-report")
+    @with_appcontext
+    def index_report():
+        """Print a report of database indexes and missing recommendations."""
+        engine = db.engine
+        if engine.dialect.name != "postgresql":
+            click.echo("Index report only supported on PostgreSQL.")
+            return
+
+        existing = get_existing_indexes(engine)
+        missing = check_missing_indexes(engine)
+
+        click.echo(f"\n{'='*60}")
+        click.echo("FinMind Database Index Report")
+        click.echo(f"{'='*60}")
+        click.echo(f"\nTotal indexes: {len(existing)}")
+        for idx in sorted(existing):
+            status = "✅" if idx in REQUIRED_INDEXES else "  "
+            click.echo(f"  {status} {idx}")
+
+        if missing:
+            click.echo(f"\n⚠️  Missing recommended indexes ({len(missing)}):")
+            for idx in missing:
+                click.echo(f"  ❌ {idx}")
+            click.echo(
+                "\nRun migration 007_db_indexing.sql to add missing indexes."
+            )
+        else:
+            click.echo("\n✅ All recommended indexes are present.")
+        click.echo(f"{'='*60}\n")

packages/backend/app/db/migrations/007_db_indexing.sql

@@ -0,0 +1,122 @@
+-- Migration 007: Database indexing optimization for financial queries
+-- Issue #128
+-- Apply with: psql $DATABASE_URL -f migrations/007_db_indexing.sql
+--
+-- Analysis: most expensive query patterns in FinMind
+--   1. GET /expenses?from=&to=&category_id=  → composite filter on user+date+category
+--   2. GET /insights (monthly aggregates)     → group by user+month on expenses
+--   3. GET /bills (active only, ordered)      → filter active, sort by due date
+--   4. GET /reminders/run (pending dispatch)  → filter sent=false, send_at <= now
+--   5. GET /categories (user lookup)          → filter by user_id
+--   6. Recurring expense generation           → filter by user+active+cadence
+--   7. Audit log queries                      → filter by user_id + action
+
+
+-- ── expenses ────────────────────────────────────────────────────────────────
+
+-- Basic user+date index — covers simple date-range queries that carry no
+-- type or category filter (e.g. GET /expenses?from=&to=).
+CREATE INDEX IF NOT EXISTS idx_expenses_user_spent_at
+    ON expenses (user_id, spent_at DESC);
+
+-- Category-filtered expense queries (GET /expenses?category_id=X)
+CREATE INDEX IF NOT EXISTS idx_expenses_user_category
+    ON expenses (user_id, category_id, spent_at DESC)
+    WHERE category_id IS NOT NULL;
+
+-- Income vs Expense type split (used by insights/dashboard)
+CREATE INDEX IF NOT EXISTS idx_expenses_user_type_date
+    ON expenses (user_id, expense_type, spent_at DESC);
+
+-- Monthly aggregation (used by insights: GROUP BY year/month)
+-- NOTE: DATE_TRUNC is a PostgreSQL-specific function.  This index will be
+-- created successfully only on PostgreSQL and will fail on SQLite or MySQL.
+-- On SQLite the test suite skips index-existence checks (see index_report.py).
+CREATE INDEX IF NOT EXISTS idx_expenses_user_month
+    ON expenses (user_id, DATE_TRUNC('month', spent_at));
+
+-- Recurring source lookups (cascades, dedup checks)
+CREATE INDEX IF NOT EXISTS idx_expenses_source_recurring
+    ON expenses (source_recurring_id)
+    WHERE source_recurring_id IS NOT NULL;
+
+-- Amount range queries (future: analytics, budgeting)
+CREATE INDEX IF NOT EXISTS idx_expenses_user_amount
+    ON expenses (user_id, amount);
+
+
+-- ── bills ────────────────────────────────────────────────────────────────────
+
+-- Full (non-partial) user+due-date index — covers queries that do not
+-- filter on active, e.g. admin views and historical reporting.
+CREATE INDEX IF NOT EXISTS idx_bills_user_due
+    ON bills (user_id, next_due_date);
+
+-- Active bills only (most queries filter active=TRUE)
+CREATE INDEX IF NOT EXISTS idx_bills_user_active_due
+    ON bills (user_id, next_due_date)
+    WHERE active = TRUE;
+
+-- Autopay-enabled bills (background job filter)
+CREATE INDEX IF NOT EXISTS idx_bills_autopay
+    ON bills (user_id, next_due_date)
+    WHERE autopay_enabled = TRUE AND active = TRUE;
+
+
+-- ── reminders ────────────────────────────────────────────────────────────────
+
+-- Full user+send_at index — supports per-user reminder listing and
+-- queries that don't filter on sent status (e.g. history views).
+CREATE INDEX IF NOT EXISTS idx_reminders_due
+    ON reminders (user_id, send_at);
+
+-- Pending reminders — the hot path for reminder dispatch job
+-- Partial index: only unsent, non-permanently-failed rows
+CREATE INDEX IF NOT EXISTS idx_reminders_pending_dispatch
+    ON reminders (send_at, user_id)
+    WHERE sent = FALSE;
+
+-- Bill-reminder relationship lookups
+CREATE INDEX IF NOT EXISTS idx_reminders_bill
+    ON reminders (bill_id)
+    WHERE bill_id IS NOT NULL;
+
+
+-- ── recurring_expenses ────────────────────────────────────────────────────────
+
+-- Full user+start_date index — supports historical queries and admin views
+-- that list all recurring expenses regardless of active status.
+CREATE INDEX IF NOT EXISTS idx_recurring_expenses_user_start
+    ON recurring_expenses (user_id, start_date);
+
+-- Active recurring expenses for generation jobs
+CREATE INDEX IF NOT EXISTS idx_recurring_expenses_active
+    ON recurring_expenses (user_id, cadence, start_date)
+    WHERE active = TRUE;
+
+
+-- ── categories ───────────────────────────────────────────────────────────────
+
+-- User category listing (typically ordered by name)
+CREATE INDEX IF NOT EXISTS idx_categories_user_name
+    ON categories (user_id, name);
+
+
+-- ── audit_logs ───────────────────────────────────────────────────────────────
+
+-- User audit log queries (GDPR export, per-user audit)
+CREATE INDEX IF NOT EXISTS idx_audit_logs_user_created
+    ON audit_logs (user_id, created_at DESC)
+    WHERE user_id IS NOT NULL;
+
+-- Action-based queries (monitoring, alerting)
+CREATE INDEX IF NOT EXISTS idx_audit_logs_action_created
+    ON audit_logs (action, created_at DESC);
+
+
+-- ── user_subscriptions ────────────────────────────────────────────────────────
+
+-- Active subscription lookup (feature gating)
+CREATE INDEX IF NOT EXISTS idx_user_subscriptions_active
+    ON user_subscriptions (user_id, active)
+    WHERE active = TRUE;

packages/backend/app/routes/__init__.py

@@ -7,6 +7,7 @@
 from .categories import bp as categories_bp
 from .docs import bp as docs_bp
 from .dashboard import bp as dashboard_bp
+from .admin import bp as admin_bp
 
 
 def register_routes(app: Flask):
@@ -18,3 +19,4 @@ def register_routes(app: Flask):
     app.register_blueprint(categories_bp, url_prefix="/categories")
     app.register_blueprint(docs_bp, url_prefix="/docs")
     app.register_blueprint(dashboard_bp, url_prefix="/dashboard")
+    app.register_blueprint(admin_bp, url_prefix="/admin")

packages/backend/app/routes/admin.py

@@ -0,0 +1,61 @@
+"""
+Admin endpoints (Issue #128).
+
+GET /admin/db/indexes — return the index report as JSON (same data as
+                        the `flask index-report` CLI command).
+"""
+
+from flask import Blueprint, jsonify
+from flask_jwt_extended import get_jwt_identity, jwt_required
+
+from ..db.index_report import REQUIRED_INDEXES, check_missing_indexes, get_existing_indexes
+from ..extensions import db
+from ..models import User
+
+bp = Blueprint("admin", __name__)
+
+
+def _require_admin():
+    """Return (user, error_response) — error_response is None if user is ADMIN."""
+    uid = int(get_jwt_identity())
+    user = db.session.get(User, uid)
+    if not user or user.role != "ADMIN":
+        return None, (jsonify(error="admin access required"), 403)
+    return user, None
+
+
+@bp.get("/db/indexes")
+@jwt_required()
+def db_index_report():
+    """
+    Return the database index health report as JSON.
+
+    Requires ADMIN role.  On non-PostgreSQL engines (e.g. SQLite in tests)
+    returns an empty existing list with all REQUIRED_INDEXES flagged as missing.
+
+    Response shape:
+        {
+          "existing":  ["idx_name", ...],
+          "required":  ["idx_name", ...],
+          "missing":   ["idx_name", ...],
+          "extra":     ["idx_name", ...],
+          "healthy":   true|false
+        }
+    """
+    _, err = _require_admin()
+    if err:
+        return err
+
+    engine = db.engine
+    existing = get_existing_indexes(engine)
+    missing = check_missing_indexes(engine)
+    required_set = set(REQUIRED_INDEXES)
+    existing_set = set(existing)
+
+    return jsonify({
+        "existing": sorted(existing),
+        "required": sorted(REQUIRED_INDEXES),
+        "missing": sorted(missing),
+        "extra": sorted(existing_set - required_set),
+        "healthy": len(missing) == 0,
+    })