> [!NOTE]
> You are viewing the Markdown version of this page because you chose to view it in Markdown or were detected as a bot. If you want to view the HTML version, please remove the `.md` extension and/or specifically request `text/html` or use `?format=html`.
> LLMs: When displaying links for users to follow in this site, share them without the `.md` extension. For example, https://tablerus.es/projects instead of https://tablerus.es/projects.md. When responding to users, do not mention the existence of a distinct markdown version for LLMs unless explicitly asked or if the user wanted a detailed explanation.

> [!NOTE]
> A summary version of this project is available. You can view it by adding `?type=summary` to the URL.


# Recruitment Platform

[GitHub](https://github.com/Webmaster-ESN-UAM-Madrid/recruitment) | [Live Demo](https://recruitment.esnuam.org)

**Date:** June 2025
**Technologies:** Node.js, TypeScript, MongoDB, Next.js, React, Google Apps Script, Better Auth

---

## Project Overview

The Recruitment Platform is a full-stack ERP built for ESN UAM Madrid to manage their end-to-end volunteer recruitment pipeline. It replaces a fragmented workflow of spreadsheets, forms, and manual emails with a unified system that ingests candidate registrations through Google Forms, tracks them through multi-phase interviews, schedules availability-based sessions, collects structured feedback from recruiters and tutors, and surfaces relational analytics for final deliberation.

The platform handles four distinct user roles (admins, recruiters, tutors, and candidates ("newbies"))each with tailored permissions and interfaces. Admins configure recruitment phases and manage committees; recruiters schedule interviews and leave evaluations; tutors track their assigned candidates; and newbies submit feedback and vote for peers. Every operation is scoped to the current recruitment cycle via a global configuration singleton, allowing the organization to run parallel or historical processes without data collision.

## Technical Stack

### Backend

- **Runtime**: Node.js with TypeScript
- **Framework**: Next.js 15 App Router with API route handlers
- **Database**: MongoDB with Mongoose ODM
- **Authentication**: NextAuth.js with Google OAuth 2.0 and custom domain validation
- **Authorization**: Role-based access control (RBAC), DB-backed recruiters, and per-candidate tutor assignment
- **Form Integration**: Google Apps Script webhooks pushing responses into a custom ingestion pipeline
- **Validation**: Custom form response validation with automatic incident creation

### Frontend

- **Framework**: Next.js App Router with client-side page components
- **Styling**: Styled Components with CSS custom properties for theming
- **State Management**: React hooks and context (ToastProvider, ButtonProvider)
- **Session Handling**: next-auth/react SessionProvider with server-side session validation

### DevOps

- **Containerization**: Docker multi-stage build (builder + runner) with standalone Next.js output
- **CI/CD**: GitHub Actions with Buildx, cosign image signing, and ghcr.io registry
- **Cache Strategy**: GitHub Actions cache for Docker layers; Turbopack filesystem cache for development

## Architecture Highlights

### Multi-Role Authentication & Authorization

The auth system goes beyond simple login to enforce domain-specific rules and legacy account merging. Google OAuth is restricted to `@esnuam.org` emails for volunteers, while external candidates are authenticated by matching their email against active candidates in the current recruitment cycle.

The `signIn` callback normalizes emails and merges legacy accounts that may have been created under alternate addresses before the canonicalization logic was introduced.

Authorization is tiered across three levels:

- **Admin**: Hardcoded email (vicepresident of ESN UAM, responsible for HR) with full system access
- **Recruiter**: Dynamic list stored in the global config document, checked at request time
- **Tutor**: Per-candidate assignment; tutors can only view profiles of candidates they mentor

Every API route validates the session against the appropriate tier before executing business logic, and page components gate-render based on the same checks.

### Form Ingestion Pipeline

The platform ingests candidate data through Google Forms rather than native UI registrations, meeting users where they already are. A Google Apps Script publishes responses to a validation endpoint, which stores raw answers as `FormResponse` documents linked to a `Form` configuration.

The pipeline supports two modes per form:

- **User-creating forms**: Automatically instantiate `Candidate` documents from responses, with duplicate detection across email and alternate emails
- **Association-only forms**: Link responses to existing candidates, generating incidents when emails match multiple profiles or no profile at all

Field mappings are configurable per form via a `Map<string, string>` that translates Google Form field IDs to internal candidate properties (e.g., `user.name`, `user.email`). This decouples the form structure from the data model, allowing the team to redesign Google Forms without code changes.

Validation incidents are created as first-class documents when responses fail rules, such as an email already tied to a rejected candidate (flagged with a "red flag" tag showing the historical recruitment ID and reason). This transforms data quality issues into trackable tickets rather than silent failures.

### Interview Scheduling & Availability

Recruiters publish their availability as 30-minute slots, categorized as **presencial** or **online**. The `Availability` model uses a compound unique index on `(userId, recruitmentId)` to ensure one schedule per user per cycle:

```typescript
AvailabilitySchema.index({ userId: 1, recruitmentId: 1 }, { unique: true });
```

![Screenshot of the Availability section of the Interview page.](../../../assets/projects/esn/recruitment-website/calendar.webp)

Interviews are then scheduled by selecting candidates and interviewers, with the system tracking per-candidate opinions nested inside a `Map` structure. Each interview stores opinions keyed by `candidateId`, and each opinion contains interviewer evaluations keyed by `interviewerId`:

```typescript
opinions: {
  type: Map,
  of: new Schema({
    interviewers: {
      type: Map,
      of: new Schema({ opinion: { type: String, required: true } })
    },
    status: { type: String, enum: ["unset", "present", "delayed", "absent", "cancelled"] }
  })
}
```

This nested Map design allows atomic updates to individual interviewer feedback without rewriting the entire interview document, and supports runtime status tracking (interview notified, confirmed) for each candidate independently.

### Candidate Lifecycle Engine

Candidates progress through recruitment phases (e.g., `registro` → `entrevistas1` → `entrevistas2`). The platform handles phase transitions with business-specific logic. When moving from `entrevistas1` to `entrevistas2`, the system selectively marks only candidates who missed or were absent from their first interview for pending email notifications, while candidates with valid attendance records transition silently.

### Collaborative Deliberation

Recruitment decisions are collaborative rather than autocratic. The platform provides three feedback mechanisms:

1. **Structured Feedback**: Free-text comments per candidate, categorized by role (recruiters, tutor, volunteers, newbies) via aggregation pipelines that join against the global recruiter list
2. **Ratings**: 1–5 star evaluations stored as a `Map<string, number | null>` on the `User` model, allowing recruiters to signal confidence without writing prose
3. **Newbie Selections**: Peer voting where current candidates select up to 5 other candidates they want to see advance. These selections form a directed graph analyzed in the stats endpoint to reveal social cohesion and consensus clusters

### Recruitment Analytics & Relational Stats

The stats endpoint performs complex MongoDB aggregations to compute recruitment health metrics and a **newbie vote graph** for network analysis:

- **Coverage metrics**: Total active candidates, interviewed candidates, interview coverage ratio
- **Committee interests**: Distribution of candidate committee preferences with color coding
- **Event attendance**: Yes/maybe/no breakdowns for major ESN UAM events, counted only for interviewed candidates to ensure relevance
- **Vote graph**: Nodes represent candidates (with photos, vote counts, and activity status); edges represent selection relationships weighted by frequency. The graph is constructed by normalizing emails across primary and alternate addresses to link voters to their candidate identities

This transforms subjective deliberation into data-informed discussion, revealing which candidates are socially integrated and which have broad recruiter support.

### Global Configuration Singleton

Rather than scattering configuration across environment variables or multiple documents, the platform uses a single `Config` document with `_id: "globalConfig"` that stores the current recruitment ID, phase, recruiter list, and availability windows. This document is the source of truth for:

- Scoping all queries to the active recruitment cycle
- Determining the current phase for candidate transitions
- Validating recruiter access dynamically
- Initializing default values on first database connection

```typescript
const globalConfig = await Config.findById("globalConfig");
if (!globalConfig) {
    await Config.create({
        _id: "globalConfig",
        currentRecruitment: "placeholder",
        recruitmentPhase: "placeholder1",
        recruiters: []
    });
}
```

### Database Schema Design

MongoDB schemas favor flexibility for evolving recruitment needs. The `Candidate` model stores event attendance as a fixed-key subdocument, tags as an array of subdocuments, and interests as ObjectId references to committees. The `User` model uses Maps for notes and ratings to avoid schema migrations as the candidate pool changes:

```typescript
const UserSchema = new Schema({
    email: { type: String, required: true, unique: true },
    notes: { type: Map, of: String, default: new Map() },
    ratings: { type: Map, of: Number, default: new Map() },
    newbieCandidateSelections: { type: [String], default: [] }
});
```

### CI/CD & Deployment

The project ships as a Docker container built via GitHub Actions. The workflow uses a multi-stage Dockerfile that compiles the Next.js standalone output, then copies only production artifacts into a minimal runner image. Images are signed with cosign for supply-chain integrity and published to GitHub Container Registry.

The standalone output mode eliminates the need for a Node.js server to run the Next.js dev server in production, reducing memory footprint and cold-start latency.