Instruction file imported from TheUnshackled1/capstone-talisay_housing (.cursor/rules/staff-dashboard-perf.mdc). Copyright stays with the author.

Staff page performance (Railway)

Never do this on second/fourth-member dashboards

• Do not call _module2_applicant_row_payload or _module2_eligibility_snapshot from _staff_analytics_module2_counts / _staff_reports_analytics_payload.
• Clear document/household prefetches on the analytics path (.prefetch_related(None) + .iterator()).
• Do not restore the old _get_session_monitoring_data (24 hourly Session counts + session decode). Keep the lightweight aggregate-only version.

Never do this on intake Registered Applicants

• Do not select_related('blob_record') when building document download URLs for list pages. That loads DocumentBlob.data (tens of MB) into memory and aborts gunicorn.
• Use Exists(DocumentBlob…) / annotated has_blob and Document.absolute_download_url (existence-only).
• Do not call check_blacklist_module2 once per archive row. Use _intake_blacklist_payloads_for_applicants (one Units blacklist prefetch + in-process match).

Required pattern

• Dashboard counts: light pass over _module2_evaluations_applicants_queryset() + _module2_on_ready_for_form_queue_track only.
• Prefer prefetched related collections (.all() in Python) over per-row .filter().count() when the queryset already prefetch_relateds.
• Cache stable Requirement lookups (see _cached_required_group_a_vault_doc_types) instead of querying inside per-applicant loops.
• ISF population: never combine .iterator() with prefetch_related (iterator disables prefetch → N+1).

Procfile

Keep startup as: migrate --skip-checks → optional media seed into $MEDIA_ROOT → gunicorn with --timeout 180. Do not strip migrate/media seed when editing the Procfile.

Regression

StaffDashboardAnalyticsPerfGuardTests in accounts/tests.py must keep passing.