RoleMate

RoleMate is a platform designed to help job seekers practice interviews by instantly connecting them with other candidates preparing for similar roles. It features real-time matchmaking with preference-based scoring, text chat, WebRTC video calls, and post-session feedback.

Quick Start (Docker)

The easiest way to run the full stack:

docker compose up --build

Visit http://localhost:3000 — PostgreSQL, backend, and Nginx frontend all start automatically.

Local Development

Prerequisites

• Java 25+ and Maven 3.9+ (backend)
• Node.js 20+ and npm (frontend)
• PostgreSQL 18 running locally

Backend

cd backend
mvn spring-boot:run        # Starts on http://localhost:8080
mvn test                   # Run all tests (55 tests)

Frontend

cd frontend
npm install
npm run dev                # Starts on http://localhost:5173 (proxies API/WS to :8080)

TURN Server (Optional)

WebRTC video calls use free Google STUN servers by default. For users behind restrictive NATs/firewalls, you can add a TURN relay server:

1. Copy the environment template:

   cp frontend/.env.example frontend/.env

2. Fill in your TURN credentials:

   VITE_TURN_URL=turn:your-turn-server.com:3478
   VITE_TURN_USERNAME=your_username
   VITE_TURN_CREDENTIAL=your_credential

The app automatically detects these variables — if they're absent, it falls back to STUN-only mode. For Docker deployments, pass them as build args or inject them into the frontend container.

Recommended TURN providers: Metered.ca, Twilio Network Traversal, or self-hosted coturn.

API Endpoints

Endpoint	Description
GET /api/health	Health check with live stats
GET /api/roles	Supported role categories
GET /api/topics	Topic catalog (role → topics)
GET /api/queue/status	Current queue sizes per role
WS /ws/matchmaking	WebSocket matchmaking connection

Tech Stack

Layer	Technology
Backend	Java 25, Spring Boot 3.5, Spring WebSocket
Frontend	React (Vite), Vanilla CSS
Database	PostgreSQL 18 (Flyway migrations)
Video	WebRTC (STUN + optional TURN)
Infrastructure	Docker, Nginx reverse proxy

Project Structure

RoleMate/
├── backend/                    # Spring Boot application
│   ├── src/main/java/          # Matchmaking, signaling, persistence
│   └── src/main/resources/     # application.properties, Flyway migrations
├── frontend/                   # React + Vite application
│   ├── src/components/         # UI components
│   ├── src/hooks/              # useWebSocket, useWebRTC, useSoundEffects
│   └── .env.example            # TURN server configuration template
├── docker-compose.yml          # Full-stack orchestration
└── rolemate documentation/     # ROADMAP.md, product overview, guides

Documentation: For the detailed roadmap, architecture decisions, and milestone history, see the rolemate documentation/ folder.