EchoHire

EchoHire is an AI-powered recruitment and interview platform developed as a Final Year Project. It combines candidate and recruiter workflows, a Next.js web application, a FastAPI backend with asynchronous processing, PostgreSQL-backed persistence and vector matching, and a dedicated Hugging Face model service for interview-question generation.

Project Context

EchoHire is an academic capstone, not a commercial production deployment. Its scope demonstrates how a multi-role recruitment workflow can be implemented across independent web, API, data, background-worker, and applied-AI components.

The Problem

Recruitment workflows require candidates to turn profile and resume information into discoverable applications, while recruiters need to create roles, review applicants, configure interviews, and compare suitable candidates. EchoHire implements these connected workflows in one system, including structured profile/resume processing, job applications, interview-question generation, and skill-vector recommendation flows.

The Solution

The repository keeps the four services independently runnable while documenting and versioning them as one project. The frontend calls the backend API; the backend owns application data and background jobs; its interview worker calls the isolated model service; and PostgreSQL supplies the local persistence layer.

System Architecture

flowchart TD
    U[Candidate / Recruiter] --> F[Next.js Frontend]
    F -->|authenticated HTTP| B[FastAPI Backend]
    B --> P[(PostgreSQL)]
    B --> R[(Redis)]
    B --> C[Celery Worker]
    C -->|MODEL_URL| M[Model Service]
    P --> V[pgvector similarity queries]

Frontend

frontend/ is the Next.js candidate and recruiter experience. It manages Clerk-authenticated browser interactions, Firebase resume uploads, job and application views, and the interview UI.

Backend

backend/ is the FastAPI API and business-logic layer. It uses SQLAlchemy/Alembic with PostgreSQL, manages authentication-backed workflows, runs Celery interview-generation tasks through Redis, and calls the model service through MODEL_URL.

Model Service

model/ isolates custom Hugging Face causal-language-model inference. Its FastAPI endpoint and Cog predictor generate interview-question text from a job title and skills.

Database Infrastructure

database/ provides the local PostgreSQL 17 and pgAdmin Docker Compose stack plus first-run SQL bootstrap. The backend owns the Alembic migration that enables pgvector; the current database Compose image itself is standard PostgreSQL and does not bundle pgvector.

Core Capabilities

Candidate Experience

• Resume upload and structured profile onboarding.
• Job browsing, bookmarking, applications, application tracking, and dashboard counts.
• Text-based interviews with question navigation, timing, and answer submission.

Recruiter Experience

• Company-profile onboarding and job-posting management.
• Applicant review, profile/report access, resume download, and application-status updates.
• Interview-question generation, readiness polling, and question editing.

AI Interview and Matching

• A dedicated model service produces interview-question text from job title and skills.
• The backend queues generation work with Celery and Redis.
• Backend candidate/job vectors support pgvector similarity queries for recommendation routes.

End-to-End Workflows

Candidate: authenticate → upload a resume or complete the profile form → browse, save, or apply for jobs → complete an available text interview → view application-related information.

Recruiter: authenticate → complete company profile → create a job → request interview questions → review applicants and reports → update application status or load job-specific recommendations.

Engineering Highlights

• Next.js App Router UI with separate candidate and recruiter areas.
• FastAPI API with SQLAlchemy models, Alembic migrations, and Clerk-backed authorization integration.
• Celery/Redis background processing for interview generation.
• PostgreSQL plus backend-managed pgvector extension and vector similarity queries.
• Isolated Hugging Face Transformers/Cog inference service.
• Docker Compose database boundary that remains independent of application runtimes.

Repository Structure

EchoHire/
├── frontend/   # Next.js web application
├── backend/    # FastAPI API, Celery tasks, and migrations
├── model/      # Hugging Face/Cog inference service
├── database/   # PostgreSQL and pgAdmin local infrastructure
└── docs/       # System-level architecture notes

Technology Stack

• Frontend: Next.js 15, React 19, Tailwind CSS, Clerk, Firebase Storage.
• Backend: Python, FastAPI, SQLAlchemy, Alembic, Celery.
• AI / ML: Hugging Face Transformers, PyTorch, Cog.
• Data: PostgreSQL 17, pgvector (backend migration and queries), pgAdmin.
• Async / real-time: Redis and Celery. WebSocket dependencies are present, although the currently tracked backend router registration is commented out.
• Infrastructure: Docker and Docker Compose for the model image and database stack.

Running EchoHire

Each component remains independently runnable from its own directory. Configure the required environment variables in local, uncommitted environment files, then generally start services in this order:

1. Use Node 22.23.2 for the frontend (frontend/.nvmrc), then start PostgreSQL (and pgAdmin if needed) from database/.
2. Start Redis for backend background tasks.
3. Start the model service if interview generation is needed, and set the backend MODEL_URL to its /generate-questions endpoint.
4. Start the backend on port 8000 and its Celery worker.
5. Start the frontend on port 3000 with NEXT_PUBLIC_API_URL pointed at the backend.

The exact dependencies, required variables, and commands are documented in each component README.

Current Status

The repository consolidates the implemented FYP components without merging their runtimes or business logic. It includes the candidate and recruiter web workflows, FastAPI API layer, background interview-generation task flow, model-serving artifacts, and local database infrastructure described in the component documentation.

Limitations

• Local configuration requires external Clerk, Firebase, PostgreSQL, Redis, and model-artifact setup.
• The database Compose image does not itself provide pgvector, even though the backend migration and models expect it for vector features.
• The model service requires separately provisioned model weights for its FastAPI/Docker path and returns raw generated text rather than validated question structures.
• The frontend has hardcoded local API URLs in a small number of flows, in addition to its environment-based API URL.
• Automated test coverage is limited by the component repositories' current scripts and configuration.

Academic Context

EchoHire originated as a Final Year Project and demonstrates full-stack UI work, backend/API design, asynchronous processing, relational and vector-oriented data access, Dockerized local infrastructure, and applied language-model integration.