Core Components

This document describes the high-level components, technology stack, and module architecture of the api.faculytics project.

api.faculytics serves as an intermediary layer between Moodle and local institutional data. Its primary responsibilities include:

• Authentication: Authenticating users via Moodle tokens and issuing local JWTs.
• Data Synchronization: Mirroring Moodle's institutional hierarchy (Campuses, Semesters, Departments, Programs) and course enrollments.
• Entity Management: Maintaining a normalized local database for analytics and extended features.
• Questionnaire Management: Managing weighted questionnaires for student and faculty feedback. See Questionnaire Management for detailed architecture.

• Backend Framework: NestJS (v11)
• Database ORM: MikroORM with PostgreSQL
• Authentication: Passport.js (JWT and Refresh Token strategies)
• External API: Moodle Web Services (REST)
• Task Scheduling: NestJS Schedule (Cron)
• Caching: @nestjs/cache-manager with Redis (@keyv/redis)
• Job Queue: BullMQ (@nestjs/bullmq) on Redis
• Health Checks: @nestjs/terminus with custom indicators
• PDF Generation: Puppeteer (headless Chrome) + Handlebars templates
• Object Storage: Cloudflare R2 via @aws-sdk/client-s3 with presigned URL downloads
• Validation: Zod (Environment variables), class-validator (DTOs)

The application is structured into Infrastructure and Application layers, coordinated by the AppModule.

Authentication uses a priority-based strategy pattern (src/modules/auth/strategies/). Each strategy implements the LoginStrategy interface:

• CanHandle(localUser, body): Determines if this strategy applies to the login request.
• Execute(em, localUser, body): Performs authentication and returns the user + optional Moodle token.
• priority: Numeric ordering (lower = higher precedence).

Priority ranges: 0-99 core auth, 100-199 external providers, 200+ fallbacks. To add a new provider, implement LoginStrategy and register it under the LOGIN_STRATEGIES injection token.

Institutional sync (categories, courses, enrollments) uses a BullMQ-based composite job instead of individual cron jobs. See Institutional Sync Workflow for the full flow.

Phase dependency: if categories fail, courses and enrollments are skipped. If courses fail, enrollments are skipped.

Cron jobs using the BaseJob pattern:

The MoodleClient enforces a 10-second timeout (MOODLE_REQUEST_TIMEOUT_MS) on all Moodle API calls via AbortSignal.timeout(). Network failures are wrapped in MoodleConnectivityError:

• Timeout: "Moodle request timed out during {operation}"
• Connection failure: "Failed to connect to Moodle service during {operation}"
• General network error: "Network error during Moodle {operation}"

The MoodleLoginStrategy catches MoodleConnectivityError and translates it to a 401 Unauthorized with a user-friendly message.

The AnalysisModule provides a multi-stage analysis pipeline that orchestrates AI processing of qualitative feedback. See AI Inference Pipeline for the full architecture and Analysis Pipeline Workflow for the stage-by-stage flow.

The PipelineOrchestratorService manages the full analysis lifecycle through a confirm-before-execute pattern:

1. Create — Computes coverage stats (response rate, submission/comment counts) and generates warnings
2. Confirm — Validates configuration and dispatches the first stage
3. Stage progression — Each processor calls back into the orchestrator to advance to the next stage
4. Terminal states — COMPLETED, FAILED, or CANCELLED

AWAITING_CONFIRMATION → SENTIMENT_ANALYSIS → SENTIMENT_GATE → TOPIC_MODELING → TOPIC_LABELING → GENERATING_RECOMMENDATIONS → COMPLETED

Each stage has a corresponding RunStatus (PENDING → PROCESSING → COMPLETED / FAILED).

Eight BullMQ queues with independent concurrency. Queue names are centralized in src/configurations/common/queue-names.ts.

See Analytics Module for full architecture.

See Report Generation Workflow for the full async flow.

Resilience: Exponential backoff retries, stall detection, graceful degradation when Redis is unavailable (ServiceUnavailableException), HTTP timeout via AbortController.

Local development: docker compose up starts Redis and a mock worker (Hono HTTP server on port 3001) that simulates worker responses.

The HealthModule uses @nestjs/terminus to provide structured health checks at GET /health:

Returns HTTP 200 with status: 'ok' when healthy, HTTP 503 with status: 'error' and per-indicator details when unhealthy.

The FacultyModule and CurriculumModule use a shared role-based scoping pattern for administrative queries. This ensures deans only see data within their assigned departments while super admins see everything.

Request → JwtAuthGuard → RolesGuard → CurrentUserInterceptor → CLS Store → ScopeResolverService

1. @UseJwtGuard(SUPER_ADMIN, DEAN, CHAIRPERSON) validates JWT and checks role membership via RolesGuard
2. CurrentUserInterceptor loads the full User entity via UserLoader and stores it in CLS (CurrentUserService.set())
3. ScopeResolverService.ResolveDepartmentIds(semesterId) reads the user from CLS and returns:
   • null — unrestricted (super admin)
   • string[] — department UUIDs the dean is assigned to for that semester
   • string[] — department UUIDs derived from the chairperson's program assignments
4. ScopeResolverService.ResolveProgramIds(semesterId) provides program-level granularity:
   • null — unrestricted (super admin, dean)
   • string[] — program UUIDs the chairperson is assigned to

When explicit filter params (departmentId, programId) are provided, they are validated against the resolved scope:

Both modules import CommonModule (for ScopeResolverService) and DataLoaderModule (for CurrentUserInterceptor → UserLoader).

The CurriculumModule endpoints return flat arrays (no pagination) since result sets are small within a dean's scope. All three endpoints require semesterId; the courses endpoint additionally requires at least one of programId or departmentId to prevent unbounded queries.

The application enforces a strict initialization sequence in InitializeDatabase before it begins accepting traffic. This ensures that the database schema and required infrastructure state are always synchronized with the code.

1. Migration (orm.migrator.up()): Automatically applies any pending database migrations.
2. Infrastructure Seeding (orm.seeder.seed(DatabaseSeeder)): Executes idempotent seeders (e.g., DimensionSeeder) to populate required reference data.
3. Application Bootstrap: Only after both steps succeed does app.listen() execute. If any step fails, the process exits with code 1.