tausif-islam-sheik/hireiq-server

1. Repository shape

This is a TypeScript/Node.js backend for HireIQ, built as an Express API server with a clear layered structure: routes → controllers → services → persistence/integrations. It is not the frontend; the frontend lives in a separate Next.js repo.

2. Primary runtime and deployment boundary

The server targets Node 20+, uses pnpm, and is designed for Render deployment (render.yaml, RENDER_DEPLOY.md). The app entry point is src/server.ts, with shared bootstrap/config concerns isolated from domain logic.

3. HTTP API layer

Each domain has its own route module under src/routes: auth, user, job, application, company, resume, savedJob, notification, and ai. These routes map requests to controller modules in src/controllers, keeping request handling separated by business area.

4. Controller orchestration layer

Controllers are the main orchestration boundary. They validate/shape incoming requests, enforce access rules via middleware, and delegate to services or AI modules. The controller set reflects the product’s core workflows: authentication, job management, application pipelines, resume handling, saved jobs, notifications, and AI features.

5. Core business services

The src/services directory holds the application’s business logic for auth, jobs, applications, saved jobs, notifications, email, and uploads. These services are the main boundary between HTTP/API concerns and infrastructure concerns, and they likely coordinate Prisma reads/writes plus external providers.

6. AI subsystem

AI logic is isolated under src/ai with focused modules for resume analysis, candidate ranking, interview coaching, and job-description generation. aiClient.ts is the central integration point for model/provider calls. The README indicates OpenRouter/OpenAI-style LLM usage, and the presence of jdGenerator, resumeAnalyzer, and interviewCoach shows the AI layer is used for recruitment-specific content generation and scoring, not generic chat.

7. Resume processing pipeline

Resume handling is split between parsing and AI analysis. src/lib/resumeParser.ts extracts text from uploaded documents, while the AI modules consume that parsed content for screening and quality analysis. This creates a distinct pipeline: file upload → text extraction → AI scoring/generation → persistence and/or user-facing results.

8. Persistence layer

PostgreSQL is the system of record, accessed through Prisma (prisma/schema.prisma, migrations under prisma/migrations, and src/lib/prisma.ts). The schema/migration history shows evolving recruitment data models, including saved jobs and user-state fields such as verification/activation. src/seed.ts suggests a bootstrap dataset for local/dev environments.

9. Background processing and caching

src/queues/emailQueue.ts and src/queues/resumeQueue.ts indicate asynchronous jobs for longer-running work, backed by Redis (src/lib/redis.ts). This separates latency-sensitive API requests from work such as resume processing and outbound email delivery. Even if the worker entrypoint is not visible in this tree, the architecture clearly treats these tasks as background work rather than inline request handling.

10. Realtime and notifications

src/socket/socket.ts adds a realtime channel, likely used to push status updates such as AI screening progress, application changes, or notification events to connected clients. Notification logic also has its own controller and service, which suggests a two-step pattern: persist notification state in the database and optionally broadcast updates over sockets.

11. Cross-cutting middleware

src/middleware contains the main request guards: JWT authentication, role-based authorization, rate limiting, and centralized error handling. These define the system’s security boundary and ensure domain controllers only see authenticated/authorized requests.

12. External infrastructure and integrations

The backend integrates with Cloudinary for file storage (src/lib/cloudinary.ts), Sentry for error monitoring (src/lib/sentry.ts), logging (src/lib/logger.ts), and Redis for queues/cache. The README also points to OpenRouter/LLM credentials in environment variables, making AI calls a first-class external dependency of the service.

13. How a typical request flows

A request enters Express, passes through auth/role/rate-limit middleware, hits a domain route, and reaches a controller. The controller then calls a service or AI module, which may read/write via Prisma, enqueue background work in BullMQ/Redis, upload files to Cloudinary, or emit realtime updates through Socket.io. That separation is the key architectural boundary in this repository.