FAC-135 feat: aggregate-scope pipelines, tri-view analytics, faculty self-view

[y4nder]

Context

FAC-134 surfaced two architectural issues during manual verification:

1. Per-type pipeline scope was too narrow — the pipeline ran per questionnaireVersion, but faculty analytics need cross-type aggregation (themes drawn from all student feedback, not siloed by questionnaire type). Low-volume types produced degenerate results or empty views.
2. Faculty had no self-service analytics view — only Dean/Chairperson/Campus-Head roles could view faculty analytics. Faculty members themselves had no entry point and no redacted perspective appropriate for their role.

What was built

Backend (api.faculytics)

Phase A — Aggregate-scope pipelines

• Pipeline scope collapsed from per-questionnaireVersion to {scopeType, scopeId}. questionnaireVersion is now nullable on AnalysisPipeline.
• Qualitative-summary lookup uses $or filter to match both aggregate (questionnaireVersion = null) and legacy per-type pipelines.
• Pipeline summary/status DTOs updated for the new scope shape.

Phase B — Tiered scheduler

• TieredPipelineSchedulerJob: cron-driven pipeline scheduling with next-run calculation.
• Auto-confirm orchestrator path for scheduled (non-manual) pipeline triggers.

Tri-view backend support

• AnalysisAccessService: Faculty self-only auth — faculty users can only access their own analysis data via teaching-footprint scope check.
• New GET /analytics/faculty/:id/questionnaire-types endpoint returning per-faculty per-semester submission counts.
• RecommendedAction.facet column + migration for action categorization.

Recommendation schema tighten

• topicReference changed from optional().nullable() to nullable() — required field, null only when score-driven.
• LLM prompt copy updated to enforce this contract.
• Schema-level and integration tests added.

Frontend (app.faculytics)

Tri-view split

• Faculty report screen split into three tabs: Insights, Scores, Feedback.
• Questionnaire-type secondary tabs with per-type submission counts.
• Brand-blue tab styling (line variant for main tabs, tinted pills for sub-tabs).

Faculty self-view

• /faculty/analytics auto-resolves the current semester from the user's campus.
• Feedback tab redacted entirely for Faculty role.
• Theme explorer cards hide "What Students Say", "All Comments", and sentiment breakdown — only Suggested Action is shown.
• Back button routes to /faculty/courses with role-aware label.

Bug fixes

• Fixed stale qualitative-summary cache after pipeline regeneration (transition-detecting invalidation).
• Hardened questionnaireTypeCode derivation to never produce empty strings.
• Removed dead facet lens from Insights tab.
• Fixed ?facet= URL param auto-strip for old bookmarks.

PRs

• API: FAC-135 feat: aggregate-scope pipelines, tiered scheduler, tri-view backend #349
• Frontend: FAC-WEB feat: tri-view faculty analytics + faculty self-view with redactions app.faculytics#88

Acceptance criteria

• Aggregate-scope pipelines correctly found by qualitative-summary endpoint
• Legacy per-type pipelines still matched via $or fallback
• Faculty user can only access their own analysis data
• /questionnaire-types endpoint returns per-faculty submission counts
• Recommendation topicReference enforced as required-or-null (not optional)
• Faculty self-view at /faculty/analytics auto-resolves semester
• Faculty sees only Insights + Scores (Feedback tab hidden)
• Faculty theme cards show only Suggested Action (no comments, no sentiment breakdown)
• Pipeline completion invalidates qualitative-summary cache
• questionnaireTypeCode never sent as empty string to API
• All backend tests pass (1028 tests)
• Frontend typecheck + lint clean

Related

• FAC-134 (surfaced the per-type scope problem during verification)
• FAC-132 (original pipeline infrastructure)

[y4nder]

Execution sequence (agreed post-FAC-134)

FAC numbers were re-assigned to reflect this order.

#	FAC	Issue	Why this position
1	FAC-135	#345	Low-volume handling — real bug, confusing empty state today
2	FAC-136	#343	Pipeline identity — architectural root; stable identity before recs decoupling
3	FAC-137	#340	Decouple recommendations — builds cleanly on FAC-136's identity
4	FAC-138	#342	Prompt redesign — iterates easily once FAC-137 decouples regen
5	FAC-139	#341	Multi-scope recs — needs both FAC-136 identity and FAC-137 decoupling
6	FAC-140	#344	All-comments browser — benefits from FAC-136 cross-role visibility
7	FAC-141	#346	Dimension radar — independent, can ship anytime

This ticket is position 1 in the sequence.