feat: PostHog funnel instrumentation — five server-side events

The backend emitted exactly one custom PostHog event
(feedback_submitted), so the product funnel was invisible — no job
searches, analyses, exports, or plan-limit friction. This adds five
server-side capture_event calls at the load-bearing funnel points:

- job_searched      (routers/jobs.py)      — every /jobs/search
- resume_uploaded   (routers/workspace.py) — /resume/upload
- analysis_started  (routers/workspace.py) — sync + async analyze
- artifact_exported (routers/workspace.py) — /artifacts/export
- quota_blocked     (quota.py)             — check_and_increment +
                                             enforce_llm_budget

Events fire only after the operation succeeds, mirror the existing
feedback_submitted pattern, and carry no PII (counts / modes / tiers /
formats only). capture_event now maps a falsy distinct_id to
"anonymous" so unauthenticated funnel volume isn't dropped. A new
_event_identity helper resolves (user_id, tier) best-effort and never
raises.

See DEVLOG Day 77. Also removes a pre-existing unused Form import.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: LEANDERANTONY

backend/observability.py

@@ -266,7 +266,10 @@ def capture_event(
 
     ``distinct_id`` is the Supabase user id from the auth context on
     the request scope — never a session token or anything that could
-    leak credentials.
+    leak credentials. A falsy ``distinct_id`` (an anonymous or
+    unresolved caller) falls back to the constant ``"anonymous"`` so
+    the event is still counted — funnel volume must not silently drop
+    just because a caller wasn't signed in.
 
     All events automatically include ``product: "jobagent"`` so the
     shared PostHog project can split events by product on the
@@ -280,7 +283,7 @@ def capture_event(
         merged.update(properties)
     with suppress(Exception):
         _posthog_client.capture(
-            distinct_id=distinct_id,
+            distinct_id=distinct_id or "anonymous",
             event=event,
             properties=merged,
         )

backend/quota.py

@@ -47,6 +47,7 @@
 from datetime import datetime, timezone
 from typing import Optional
 
+from backend.observability import capture_event
 from backend.tiers import (
     TIER_CAPS,
     UNLIMITED,
@@ -512,6 +513,19 @@ def check_and_increment(
             delta=1,
         )
     except _QuotaExceededAtBackend as exc:
+        # PostHog funnel event — quota friction. Captured here rather
+        # than in the global 429 handler because this is where the
+        # user id is in scope; covers every metered TIER_CAPS counter.
+        capture_event(
+            distinct_id=user_id,
+            event="quota_blocked",
+            properties={
+                "counter": exc.counter_name,
+                "tier": tier,
+                "cap": exc.cap,
+                "current": exc.current,
+            },
+        )
         raise _build_quota_exceeded_error(
             counter_name=exc.counter_name,
             current=exc.current,
@@ -682,6 +696,17 @@ def enforce_llm_budget(
     )
     if used < cap:
         return
+    # PostHog funnel event — the weekly LLM-token budget is exhausted.
+    capture_event(
+        distinct_id=normalized_user_id,
+        event="quota_blocked",
+        properties={
+            "counter": LLM_TOKENS_COUNTER,
+            "tier": tier,
+            "cap": cap,
+            "current": used,
+        },
+    )
     raise QuotaExceededError(
         "You've used your weekly AI usage allowance on this plan. "
         "Upgrade for a higher limit, or wait for the weekly reset.",

backend/routers/jobs.py

@@ -14,6 +14,7 @@
     CACHED_JOBS_HEALTHCHECK_MONITOR_SLUG,
     CACHED_JOBS_REFRESH_MONITOR_CONFIG,
     CACHED_JOBS_REFRESH_MONITOR_SLUG,
+    capture_event,
     sentry_cron_monitor,
 )
 from backend.rate_limit import LIMIT_LLM, limiter
@@ -94,6 +95,20 @@ def search_jobs(
 
     domain_query = payload.to_domain()
     result = service.search(domain_query) if live else service.search_cached(domain_query)
+    # PostHog funnel event — the top of the job-application funnel.
+    # Server-side capture, fire-and-forget; carries no PII (counts +
+    # tier only). `quota_user_id` is "" for anonymous callers, which
+    # capture_event maps to the "anonymous" distinct id.
+    capture_event(
+        distinct_id=quota_user_id,
+        event="job_searched",
+        properties={
+            "mode": "live" if live else "cached",
+            "result_count": len(getattr(result, "results", []) or []),
+            "has_query": bool((payload.query or "").strip()),
+            "tier": tier,
+        },
+    )
     return JobSearchResponseModel.from_domain(result)
 
 

backend/routers/workspace.py

@@ -1,4 +1,4 @@
-from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
+from fastapi import APIRouter, Depends, File, HTTPException, Request, UploadFile
 from fastapi.responses import StreamingResponse
 
 from backend.observability import capture_event
@@ -125,6 +125,35 @@ def _resolve_export_tier(access_token: str, refresh_token: str):
     return resolve_user_tier(app_user)
 
 
+def _event_identity(access_token: str, refresh_token: str) -> tuple[str, str]:
+    """Best-effort ``(user_id, tier)`` for a PostHog funnel event.
+
+    NEVER raises — analytics attribution must not be able to break a
+    route. An anonymous or unresolvable caller resolves to
+    ``("", "free")``; ``capture_event`` maps the empty id to the
+    "anonymous" distinct id, so the event is still counted.
+    """
+    if not (access_token and refresh_token):
+        return ("", "free")
+    try:
+        auth_context = resolve_authenticated_context(
+            access_token=access_token,
+            refresh_token=refresh_token,
+        )
+    except Exception:  # noqa: BLE001 — analytics identity is best-effort
+        return ("", "free")
+    app_user = getattr(auth_context, "app_user", None) if auth_context else None
+    if app_user is None:
+        return ("", "free")
+    return (str(getattr(app_user, "id", "") or ""), resolve_user_tier(app_user))
+
+
+def _file_extension(filename: str | None) -> str:
+    """Lower-cased file extension without the dot, or "" when absent."""
+    name = str(filename or "")
+    return name.rsplit(".", 1)[-1].lower() if "." in name else ""
+
+
 def _resolve_openai_service(access_token: str, refresh_token: str):
     """Best-effort OpenAIService for an authenticated request.
 
@@ -243,13 +272,24 @@ def upload_resume(
     """
     access_token, refresh_token = auth_tokens
     try:
-        return parse_resume_upload(
+        result = parse_resume_upload(
             filename=payload.filename,
             mime_type=payload.mime_type,
             content_base64=payload.content_base64,
             access_token=access_token or "",
             refresh_token=refresh_token or "",
         )
+        # PostHog funnel event — resume intake (upload path).
+        user_id, tier = _event_identity(access_token or "", refresh_token or "")
+        capture_event(
+            distinct_id=user_id,
+            event="resume_uploaded",
+            properties={
+                "tier": tier,
+                "file_type": _file_extension(payload.filename),
+            },
+        )
+        return result
     except AppError as error:
         _raise_http_error(error)
 
@@ -673,7 +713,7 @@ def analyze_workspace(
 ):
     access_token, refresh_token = auth_tokens
     try:
-        return run_workspace_analysis(
+        result = run_workspace_analysis(
             resume_text=payload.resume_text,
             resume_filetype=payload.resume_filetype,
             resume_source=payload.resume_source,
@@ -684,6 +724,21 @@ def analyze_workspace(
             access_token=access_token or "",
             refresh_token=refresh_token or "",
         )
+        # PostHog funnel event — the core product action (supervised
+        # pipeline). `mode` distinguishes the synchronous route from
+        # the async job route below.
+        user_id, tier = _event_identity(access_token or "", refresh_token or "")
+        capture_event(
+            distinct_id=user_id,
+            event="analysis_started",
+            properties={
+                "mode": "sync",
+                "tier": tier,
+                "premium": bool(payload.premium),
+                "run_assisted": bool(payload.run_assisted),
+            },
+        )
+        return result
     except AppError as error:
         _raise_http_error(error)
 
@@ -700,7 +755,7 @@ def start_workspace_analysis_job_route(
 ):
     access_token, refresh_token = auth_tokens
     try:
-        return start_workspace_analysis_job(
+        result = start_workspace_analysis_job(
             resume_text=payload.resume_text,
             resume_filetype=payload.resume_filetype,
             resume_source=payload.resume_source,
@@ -710,6 +765,19 @@ def start_workspace_analysis_job_route(
             access_token=access_token or "",
             refresh_token=refresh_token or "",
         )
+        # PostHog funnel event — async variant of the supervised
+        # pipeline. Emitted once the job is accepted onto the queue.
+        user_id, tier = _event_identity(access_token or "", refresh_token or "")
+        capture_event(
+            distinct_id=user_id,
+            event="analysis_started",
+            properties={
+                "mode": "async",
+                "tier": tier,
+                "premium": bool(payload.premium),
+            },
+        )
+        return result
     except WorkspaceRunJobCapacityError:
         raise HTTPException(
             status_code=503,
@@ -1107,13 +1175,29 @@ def export_workspace_artifact_route(
         themes=(payload.resume_theme, payload.cover_letter_theme),
     )
     try:
-        return export_workspace_artifact(
+        result = export_workspace_artifact(
             workspace_snapshot=payload.workspace_snapshot,
             artifact_kind=payload.artifact_kind,
             export_format=payload.export_format,
             resume_theme=payload.resume_theme,
             cover_letter_theme=payload.cover_letter_theme,
         )
+        # PostHog funnel event — the conversion point: the user took an
+        # artifact away. Theme + format properties show which export
+        # options actually get used.
+        user_id, tier = _event_identity(access_token or "", refresh_token or "")
+        capture_event(
+            distinct_id=user_id,
+            event="artifact_exported",
+            properties={
+                "artifact_kind": payload.artifact_kind,
+                "export_format": payload.export_format,
+                "resume_theme": payload.resume_theme,
+                "cover_letter_theme": payload.cover_letter_theme,
+                "tier": tier,
+            },
+        )
+        return result
     except AppError as error:
         _raise_http_error(error)
 

docs/DEVLOG.md

@@ -3908,3 +3908,52 @@ checks, both hard-failure paths, and the degraded → ERROR-log alerting
 contract; `health_stats` store tests and `/admin/refresh-healthcheck`
 endpoint tests round it out. `cached_jobs_health_stats` is applied to
 the live database.
+
+## Day 77: PostHog funnel instrumentation — five server-side events
+
+A PostHog audit (the "Job Agent — Product Health" dashboard built
+alongside this work) found the product almost entirely
+un-instrumented: the backend emitted exactly one custom event,
+`feedback_submitted`. PostHog could see feedback and browser
+autocapture and nothing else — no job searches, no analyses, no
+exports, no plan-limit friction. You cannot visualise a funnel you
+never recorded.
+
+This slice records it. Five server-side `capture_event` calls at the
+load-bearing points of the job-application funnel:
+
+- **`job_searched`** (`routers/jobs.py`) — every `/jobs/search`. Props:
+  cached-vs-live mode, result count, has-query, tier.
+- **`resume_uploaded`** (`routers/workspace.py`) — `/resume/upload`.
+  Props: file type, tier.
+- **`analysis_started`** (`routers/workspace.py`) — both the sync
+  `/analyze` and the async `/analyze-jobs` route, distinguished by a
+  `mode` property. The core product action.
+- **`artifact_exported`** (`routers/workspace.py`) —
+  `/artifacts/export`. Props: artifact kind, format, themes, tier —
+  the conversion point.
+- **`quota_blocked`** (`quota.py`) — emitted at the two
+  `QuotaExceededError` raise sites that carry a user id
+  (`check_and_increment`, covering all metered counters, and
+  `enforce_llm_budget`). The friction signal: which plan limit are
+  users hitting.
+
+Design notes. Every event is emitted from the router (or, for
+`quota_blocked`, the quota module) — never the `src/` core, which must
+not depend on `backend/`. Each fires only AFTER the operation
+succeeds, mirroring the existing `feedback_submitted` precedent;
+`capture_event` is fire-and-forget and swallows every exception, so an
+analytics failure can never break a route. A new `_event_identity`
+helper resolves `(user_id, tier)` best-effort and never raises.
+`capture_event` now maps a falsy `distinct_id` to the constant
+`"anonymous"` so an unauthenticated job search still counts toward
+funnel volume instead of silently dropping. No PII in any property —
+counts, modes, tiers, formats, themes only.
+
+Verification: 877 tests green (full suite minus the network-bound
+`nightly_eval` + quality runners; the one `.env`-only retention
+failure is unrelated and green on CI). Six new tests — `quota_blocked`
+on both raise paths, `job_searched`, `resume_uploaded`,
+`analysis_started`, `artifact_exported` — added to the existing quota,
+app, and workspace suites. Also removed a pre-existing unused `Form`
+import flagged by ruff in `routers/workspace.py`.

tests/backend/test_quota.py

@@ -636,3 +636,48 @@ def test_token_meter_isolates_users_and_weeks():
 
 def test_read_llm_token_usage_blank_user_is_zero():
     assert read_llm_token_usage("", "free") == 0
+
+
+# ─── PostHog quota_blocked funnel event ─────────────────────────────────
+
+
+def test_quota_blocked_event_captured_on_cap_breach(monkeypatch):
+    """A cap-breaching check_and_increment emits a `quota_blocked`
+    PostHog event (counter + tier + cap) before the 429 is raised."""
+    events = []
+    monkeypatch.setattr(
+        quota, "capture_event", lambda **kwargs: events.append(kwargs)
+    )
+    for _ in range(3):
+        check_and_increment("tailored_applications", "user-q", "free")
+    with pytest.raises(QuotaExceededError):
+        check_and_increment("tailored_applications", "user-q", "free")
+
+    # Only the rejected 4th call emits — the 3 successes do not.
+    assert len(events) == 1
+    event = events[0]
+    assert event["event"] == "quota_blocked"
+    assert event["distinct_id"] == "user-q"
+    assert event["properties"]["counter"] == "tailored_applications"
+    assert event["properties"]["tier"] == "free"
+    assert event["properties"]["cap"] == 3
+    assert event["properties"]["current"] == 3
+
+
+def test_quota_blocked_event_captured_on_llm_budget_rejection(monkeypatch):
+    """An exhausted weekly LLM-token meter emits `quota_blocked` with
+    the llm_tokens counter."""
+    monkeypatch.setitem(quota.TIER_CAPS["free"], LLM_TOKENS_COUNTER, 100)
+    events = []
+    monkeypatch.setattr(
+        quota, "capture_event", lambda **kwargs: events.append(kwargs)
+    )
+    record_llm_token_usage("user-llm", 100)
+    with pytest.raises(QuotaExceededError):
+        enforce_llm_budget("user-llm", "free")
+
+    assert len(events) == 1
+    assert events[0]["event"] == "quota_blocked"
+    assert events[0]["distinct_id"] == "user-llm"
+    assert events[0]["properties"]["counter"] == LLM_TOKENS_COUNTER
+    assert events[0]["properties"]["tier"] == "free"