Roadmap

This roadmap tracks the implementation status of the api.faculytics backend against the product direction. It reflects the checked-in develop branch as of 2026-04-12.

Provide a robust, analytics-driven bridge between Moodle learning environments and institutional assessment workflows, enabling data-informed decisions through synchronized academic data, asynchronous AI enrichment, and structured feedback collection from direct submissions and file-based ingestion.

Cross-cutting platform capabilities already present in the codebase but not treated as separate roadmap phases include Redis-backed caching and throttling, structured health checks, request-scoped CLS metadata, and the authenticated ChatKit endpoint.

---

• Identity Management: Moodle-integrated JWT auth with local access and refresh tokens.
• Hybrid Authentication Strategy (FAC-34): Priority-based login strategies support both local credentials and Moodle SSO.
• Robust Startup: Fail-fast bootstrap runs migrations, infrastructure seeders, and configuration validation before serving traffic.
• Institutional Hierarchy Sync: Campuses, semesters, departments, programs, courses, and enrollments are mirrored from Moodle.
• Per-User Hydration on Login: Moodle logins refresh the user's courses, enrollments, sections, and institutional roles.
• Section Sync from Moodle Groups: Course groups are materialized locally as Section and attached to enrollments.
• Institutional Authority Mapping: Dean and chairperson scope is derived from Moodle category structure, with support for manual dean assignment and a server-resolved dean-eligibility lookup for the admin UI.
• User Scope & Role Backfill During Sync: Enrollment sync now populates user.campus/program/department and derives user.roles from enrollments + institutional roles (protecting manually granted SUPER_ADMIN/ADMIN) as explicit post-enrollment phases.
• Dynamic Sync Scheduling & SyncLog Observability: Sync cadence is runtime-configurable and every run is recorded with per-phase metrics.
• Semester Label Enrichment: Moodle semester codes are parsed into display labels and academic year metadata.
• Moodle Connectivity Resilience (FAC-33): 10-second request timeouts and connectivity-specific failures prevent hanging auth and sync paths.
• Refresh Token Cleanup (FAC-35): Expired refresh tokens are purged on a 12-hour schedule with retention handling.

• Recursive Schema Validation: Questionnaire schemas enforce leaf-only questions and exact weight totals.
• Dimension Registry & Admin API: Canonical dimensions are seeded and can be managed through the dimensions module.
• Questionnaire Lifecycle Management: Questionnaires support creation, update, archive, publish, deprecate, version detail, and version-from-template flows (draft seeded from any prior published version).
• Institutional Snapshotting: Submissions persist faculty, department, program, campus, and semester snapshots for historical stability.
• Draft Save/Resume Flow: Respondents can save, retrieve, list, and delete drafts before final submission.
• Submission & Scoring: Finalized submissions validate answers, compute normalized scores, and enforce duplicate-submission rules.
• Bulk CSV Ingestion: Version-specific CSV templates and audited /questionnaires/ingest uploads support bulk submission imports.
• Ingestion Engine (Orchestrator): Stream-based processing supports dry runs, concurrency control, timeouts, and bounded error handling.
• Adapter-Based Ingestion Foundation: CSV is live in the API, and Excel adapter support exists in the ingestion layer for future exposure.
• Self-Serve File-to-Questionnaire Mapping: Imports still rely on fixed metadata headers plus question UUID columns; there is no user-defined mapping DSL or UI yet.

• BullMQ Job Queue (FAC-44): Queue-per-type analysis jobs run on Redis with retry and backoff policies.
• Pipeline Orchestrator (FAC-46): Confirm-before-execute orchestration tracks coverage, warnings, stage progression, and terminal states.
• Sentiment Analysis (FAC-46): Batch sentiment classification persists per-submission polarity scores.
• Sentiment Gate (FAC-46): Low-signal positive comments are filtered before topic modeling.
• Topic Modeling (FAC-46): Topic discovery persists assignments, keywords, and run provenance.
• Topic Labeling: Topic clusters are labeled before recommendation generation.
• Embedding Generation (FAC-46): pgvector-backed embeddings are stored and upserted per submission.
• Recommendations Engine v2 (FAC-55): Recommendations are generated directly via OpenAI with structured output, confidence, and pipeline-scoped supporting evidence (topic counts narrowed to the pipeline's submissionIds, preventing cross-faculty leakage).
• LLM Worker Hardening: Sentiment processor pins responses to the dispatched submissionId set, drops hallucinated IDs with observability logs, and terminally fails the stage when a batch is 100% hallucinated (retrying the LLM is counter-productive).
• Worker Contracts & Inference Versioning: Zod-validated contracts and version fields exist across pipeline runs.
• Local Worker Simulation: mock-worker/ supports local development without deployed inference workers.
• RunPod / Production Worker Rollout: Sentiment and topic-model stages still need production endpoint deployment and cutover.
• Pipeline Monitoring: There is no Bull Board or equivalent operator dashboard yet for failed jobs and queue health.

• Postgres-Native Analytics Strategy: Materialized views are the current analytics backbone instead of live multi-join dashboard queries.
• Snapshot-to-Analytics Refresh Pipeline: Completed analysis pipelines enqueue asynchronous analytics refresh jobs.
• Precomputed Aggregates: mv_faculty_semester_stats and mv_faculty_trends provide dashboard-ready rollups.
• Trend Analysis Engine: Trend APIs compute regression slopes and confidence (R^2) over semester history.
• Dashboard APIs: Department overview, attention list, and faculty trends endpoints are live and scope-aware.
• Faculty Evaluation Reports: Per-question reports and paginated qualitative comment endpoints are implemented.
• Analytics Freshness Tracking: analytics_last_refreshed_at is recorded so consumers can show data staleness.
• Faculty Evaluation PDF Export: Async PDF generation via BullMQ + Puppeteer, stored in Cloudflare R2 with presigned download URLs. Single and batch generation with scope-aware authorization.
• Excel Export: Excel report generation is not implemented yet.
• Long-Term OLAP Path: A broader warehouse or alternative analytical engine decision is still open if current Postgres views become a bottleneck.

• Role-Protected APIs: UseJwtGuard() and RolesGuard enforce route-level access across application modules.
• Scoped Dean/Chairperson Access: ScopeResolverService restricts analytics, curriculum, and faculty queries to authorized departments and programs.
• Institutional Role Administration: Super admins can assign and remove manual dean/chairperson roles through admin endpoints.
• Admin Directory APIs: Super-admin endpoints support user listing, filtering, and institutional role management workflows.
• Append-Only Audit Trail: Auth, sync, questionnaire, analysis, and Moodle provisioning actions are captured through the global audit pipeline.
• Audit Review Surface: GET /audit-logs and GET /audit-logs/:id expose filterable, paginated audit queries (super-admin only) with stable ordering and LIKE-pattern sanitization.
• Moodle Seeding Toolkit: API-native provisioning of categories, bulk/quick courses, and fake users replaces the external Rust CLI, with live Moodle tree inspection and cascading admin filters.
• Fine-Grained Permission Model: Access control is still role-centric rather than permission-centric.
• Notification Engine: Automated reminders and outbound notifications are still pending.
• External SIS Integration: Moodle remains the only production integration surface for institutional data.

---

1. Productionize the remaining external inference stages by replacing mock or placeholder worker URLs with deployed sentiment and topic-model endpoints.
2. Add operator visibility for BullMQ queues, sync runs, analytics refresh failures, and audit review workflows.
3. Extend the reporting surface with Excel export, department summary rollup reports, and scheduled delivery paths.
4. Mature governance from coarse role checks into a clearer permission model with explicit review tooling.
5. Reassess the analytics storage strategy once dashboard scope expands beyond the current faculty- and department-focused materialized views.