ELSA Speech Scorer

A full-stack web application for scoring candidate speech using the ELSA API. Supports two flows: a Recruiter Flow for admin-managed candidates and an Applicant Flow for self-submitted recordings.

---

Features

Recruiter Flow

• Secure login with ELSA credentials (Staging / Production environments)
• Create and manage candidate profiles
• Upload meeting transcripts and recordings
• Extract candidate speech segments using FFmpeg
• Score audio via the ELSA score_audio_plus_elsa API
• View detailed score breakdowns (EPS, fluency, pronunciation, integrity)

Applicant Flow

• Public /apply page — no login required
• In-browser audio recording (30 seconds minimum, 1 minute maximum)
• Live waveform visualiser and countdown timer
• Cycling prompts to guide the applicant
• Submissions automatically linked to a single profile by email
• Submission timestamps recorded for each entry

Candidate Dashboard

• Sortable, filterable table view of all candidates
• Filter by name, email, source (recruiter/applicant), EPS score range, and date
• Colour-coded EPS scores
• Click any row to view full candidate and meeting details

---

Tech Stack

Layer	Technology
Frontend	React 18 + TypeScript + Vite
Backend	Node.js + Express
Audio extraction	FFmpeg (via nix)
Storage	JSON file (data/candidates.json) + local uploads/
Speech scoring	ELSA score_audio_plus_elsa API

---

Project Structure

├── client/          # React frontend (Vite)
│   └── src/
│       ├── pages/
│       │   ├── ApplyPage.tsx        # Public applicant recording flow
│       │   ├── CandidatesPage.tsx   # Recruiter candidate table + filters
│       │   ├── MeetingDetailPage.tsx
│       │   └── LoginPage.tsx
│       └── components/
├── server/          # Express backend
│   ├── index.js
│   └── routes/
│       ├── apply.js      # Public POST /api/apply
│       ├── candidates.js # CRUD for candidates
│       └── scoring.js    # FFmpeg extraction + ELSA scoring
├── data/
│   └── candidates.json  # Persistent candidate data
└── uploads/             # Uploaded audio/transcript files

---

Setup

Prerequisites

• Node.js 18+
• FFmpeg (required for recruiter flow scoring)

Install & Run

# Install all dependencies
npm run build

# Start the server
npm start

The backend runs on port 3000, the frontend dev server on port 5173.

Environment

The app runs in two modes selectable at login:

• Staging — connects to ELSA staging API
• Production — connects to ELSA production API

---

API Endpoints

Method	Path	Auth	Description
POST	/api/auth/login	Public	Login with ELSA credentials
GET	/api/candidates	Required	List all candidates
POST	/api/candidates	Required	Create a candidate
GET	/api/candidates/:id	Required	Get candidate + meetings
DELETE	/api/candidates/:id	Required	Delete a candidate
POST	/api/candidates/:id/meetings	Required	Add a meeting
POST	/api/candidates/:id/meetings/:mId/upload	Required	Upload transcript/recording
POST	/api/candidates/:id/meetings/:mId/score	Required	Score a meeting
POST	/api/apply	Public	Submit an applicant recording

---

Applicant Recording Rules

Elapsed time	Available actions
0 – 29 seconds	Stop & Re-record only
30 – 59 seconds	Re-record or Stop & Submit
60 seconds	Auto-stops → goes to review

---

Deployment

The app is configured for deployment on a VM (not serverless) because:

• FFmpeg must be available at runtime
• data/candidates.json and uploads/ require persistent disk storage

npm run build   # installs deps + builds frontend
npm start       # runs server/index.js