# tausif-islam-sheik/hireiq-server architecture

> Architecture diagram of the GitHub repository tausif-islam-sheik/hireiq-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tausif-islam-sheik/hireiq-server
- Repository: https://github.com/tausif-islam-sheik/hireiq-server

## Overview

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.

Main entry points: [`src/server.ts`](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/server.ts) (Server), [`src/controllers/resume.controller.ts`](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/controllers/resume.controller.ts) (Resume Ctrl), [`src/ai/aiClient.ts`](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/ai/aiClient.ts) (AI Client), [`src/lib/prisma.ts`](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/lib/prisma.ts) (Prisma)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server["Server<br/>Express entry<br/>[server.ts]"]
end

subgraph group_api["HTTP API"]
  node_auth_routes["Auth Routes<br/>HTTP routes<br/>[auth.routes.ts]"]
  node_user_routes["User Routes<br/>HTTP routes<br/>[user.routes.ts]"]
  node_job_routes["Job Routes<br/>HTTP routes<br/>[job.routes.ts]"]
  node_application_routes["App Routes<br/>HTTP routes"]
  node_company_routes["Company Routes<br/>HTTP routes<br/>[company.routes.ts]"]
  node_resume_routes["Resume Routes<br/>HTTP routes<br/>[resume.routes.ts]"]
  node_savedjob_routes["Saved Routes<br/>HTTP routes<br/>[savedJob.routes.ts]"]
  node_notification_routes["Notify Routes<br/>HTTP routes"]
  node_ai_routes["AI Routes<br/>HTTP routes<br/>[ai.routes.ts]"]
  node_auth_controller["Auth Ctrl<br/>controller<br/>[auth.controller.ts]"]
  node_job_controller["Job Ctrl<br/>controller<br/>[job.controller.ts]"]
  node_resume_controller["Resume Ctrl<br/>controller"]
  node_notification_controller["Notify Ctrl<br/>controller"]
  node_middleware["Middleware<br/>request guards<br/>[auth.middleware.ts]"]
end

subgraph group_core["Core Logic"]
  node_auth_service["Auth Service<br/>business service<br/>[auth.service.ts]"]
  node_job_service["Job Service<br/>business service<br/>[job.service.ts]"]
  node_application_service["App Service<br/>business service"]
  node_notification_service["Notify Service<br/>business service"]
  node_upload_service["Upload Service<br/>business service<br/>[upload.service.ts]"]
  node_ai_client["AI Client<br/>LLM integration<br/>[aiClient.ts]"]
  node_resume_analyzer["Resume AI<br/>AI module<br/>[resumeAnalyzer.ts]"]
  node_candidate_ranker["Ranker<br/>AI module<br/>[candidateRanker.ts]"]
  node_jd_generator["JD Generator<br/>AI module<br/>[jdGenerator.ts]"]
  node_interview_coach["Coach<br/>AI module<br/>[interviewCoach.ts]"]
end

subgraph group_infra["Infrastructure"]
  node_prisma[("Prisma<br/>database client<br/>[prisma.ts]")]
  node_cloudinary["Cloudinary<br/>storage client<br/>[cloudinary.ts]"]
  node_redis[("Redis<br/>cache/queue client<br/>[redis.ts]")]
  node_resume_parser["Resume Parser<br/>document parser<br/>[resumeParser.ts]"]
end

subgraph group_async["Async Work"]
  node_email_queue["Email Queue<br/>background queue<br/>[emailQueue.ts]"]
  node_resume_queue["Resume Queue<br/>background queue<br/>[resumeQueue.ts]"]
end

subgraph group_realtime["Realtime"]
  node_socket(("Socket<br/>realtime channel<br/>[socket.ts]"))
end

node_server -->|"uses"| node_middleware
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_user_routes
node_server -->|"mounts"| node_job_routes
node_server -->|"mounts"| node_application_routes
node_server -->|"mounts"| node_company_routes
node_server -->|"mounts"| node_resume_routes
node_server -->|"mounts"| node_savedjob_routes
node_server -->|"mounts"| node_notification_routes
node_server -->|"mounts"| node_ai_routes
node_auth_routes -->|"calls"| node_auth_controller
node_job_routes -->|"calls"| node_job_controller
node_resume_routes -->|"calls"| node_resume_controller
node_notification_routes -->|"calls"| node_notification_controller
node_auth_controller -->|"delegates"| node_auth_service
node_job_controller -->|"delegates"| node_job_service
node_resume_controller -->|"delegates"| node_upload_service
node_resume_controller -->|"parses"| node_resume_parser
node_resume_controller -->|"enqueues"| node_resume_queue
node_notification_controller -->|"delegates"| node_notification_service
node_auth_service -->|"reads/writes"| node_prisma
node_job_service -->|"reads/writes"| node_prisma
node_application_service -->|"reads/writes"| node_prisma
node_notification_service -->|"reads/writes"| node_prisma
node_upload_service -->|"stores"| node_cloudinary
node_upload_service -->|"tracks"| node_prisma
node_resume_parser -->|"feeds"| node_resume_analyzer
node_resume_analyzer -->|"calls"| node_ai_client
node_candidate_ranker -->|"calls"| node_ai_client
node_jd_generator -->|"calls"| node_ai_client
node_interview_coach -->|"calls"| node_ai_client
node_ai_routes -->|"exposes"| node_ai_client
node_email_queue -->|"backed by"| node_redis
node_resume_queue -->|"backed by"| node_redis
node_notification_service -->|"broadcasts"| node_socket
node_notification_service -->|"queues"| node_email_queue
node_resume_controller -->|"updates"| node_socket

click node_server "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/server.ts"
click node_auth_routes "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/auth.routes.ts"
click node_user_routes "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/user.routes.ts"
click node_job_routes "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/job.routes.ts"
click node_application_routes "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/application.routes.ts"
click node_company_routes "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/company.routes.ts"
click node_resume_routes "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/resume.routes.ts"
click node_savedjob_routes "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/savedJob.routes.ts"
click node_notification_routes "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/notification.routes.ts"
click node_ai_routes "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/ai.routes.ts"
click node_auth_controller "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/controllers/auth.controller.ts"
click node_job_controller "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/controllers/job.controller.ts"
click node_resume_controller "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/controllers/resume.controller.ts"
click node_notification_controller "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/controllers/notification.controller.ts"
click node_auth_service "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/services/auth.service.ts"
click node_job_service "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/services/job.service.ts"
click node_application_service "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/services/application.service.ts"
click node_notification_service "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/services/notification.service.ts"
click node_upload_service "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/services/upload.service.ts"
click node_ai_client "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/ai/aiClient.ts"
click node_resume_analyzer "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/ai/resumeAnalyzer.ts"
click node_candidate_ranker "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/ai/candidateRanker.ts"
click node_jd_generator "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/ai/jdGenerator.ts"
click node_interview_coach "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/ai/interviewCoach.ts"
click node_prisma "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/lib/prisma.ts"
click node_cloudinary "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/lib/cloudinary.ts"
click node_redis "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/lib/redis.ts"
click node_resume_parser "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/lib/resumeParser.ts"
click node_email_queue "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/queues/emailQueue.ts"
click node_resume_queue "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/queues/resumeQueue.ts"
click node_socket "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/socket/socket.ts"
click node_middleware "https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/middleware/auth.middleware.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server toneBlue
class node_auth_routes,node_user_routes,node_job_routes,node_application_routes,node_company_routes,node_resume_routes,node_savedjob_routes,node_notification_routes,node_ai_routes,node_auth_controller,node_job_controller,node_resume_controller,node_notification_controller,node_middleware toneAmber
class node_auth_service,node_job_service,node_application_service,node_notification_service,node_upload_service,node_ai_client,node_resume_analyzer,node_candidate_ranker,node_jd_generator,node_interview_coach toneMint
class node_prisma,node_cloudinary,node_redis,node_resume_parser toneRose
class node_email_queue,node_resume_queue toneIndigo
class node_socket toneTeal
```

## Components

### Runtime

Process entrypoint and deployment boundary

- [Server](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/server.ts): Express entry · Application bootstrap and process startup · `src/server.ts`

### HTTP API

Routes and controllers for request handling

- [Auth Routes](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/auth.routes.ts): HTTP routes · Auth endpoints and request wiring · `src/routes/auth.routes.ts`
- [User Routes](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/user.routes.ts): HTTP routes · User-facing endpoints and request wiring · `src/routes/user.routes.ts`
- [Job Routes](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/job.routes.ts): HTTP routes · Job endpoints and request wiring · `src/routes/job.routes.ts`
- [App Routes](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/application.routes.ts): HTTP routes · Application workflow endpoints · `src/routes/application.routes.ts`
- [Company Routes](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/company.routes.ts): HTTP routes · Company endpoints and request wiring · `src/routes/company.routes.ts`
- [Resume Routes](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/resume.routes.ts): HTTP routes · Resume upload and screening endpoints · `src/routes/resume.routes.ts`
- [Saved Routes](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/savedJob.routes.ts): HTTP routes · Saved-job endpoints and request wiring · `src/routes/savedJob.routes.ts`
- [Notify Routes](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/notification.routes.ts): HTTP routes · Notification endpoints and request wiring · `src/routes/notification.routes.ts`
- [AI Routes](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/routes/ai.routes.ts): HTTP routes · AI feature endpoints and request wiring · `src/routes/ai.routes.ts`
- [Auth Ctrl](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/controllers/auth.controller.ts): controller · Authentication orchestration boundary · `src/controllers/auth.controller.ts`
- [Job Ctrl](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/controllers/job.controller.ts): controller · Job management orchestration · `src/controllers/job.controller.ts`
- [Resume Ctrl](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/controllers/resume.controller.ts): controller · Resume upload and analysis orchestration · `src/controllers/resume.controller.ts`
- [Notify Ctrl](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/controllers/notification.controller.ts): controller · Notification orchestration and delivery · `src/controllers/notification.controller.ts`
- [Middleware](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/middleware/auth.middleware.ts): request guards · Auth, role, rate limit, and error handling · `src/middleware/auth.middleware.ts`

### Core Logic

Business services and AI workflows

- [Auth Service](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/services/auth.service.ts): business service · Authentication and user session logic · `src/services/auth.service.ts`
- [Job Service](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/services/job.service.ts): business service · Job domain reads and writes · `src/services/job.service.ts`
- [App Service](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/services/application.service.ts): business service · Application pipeline business logic · `src/services/application.service.ts`
- [Notify Service](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/services/notification.service.ts): business service · Notification persistence and dispatch logic · `src/services/notification.service.ts`
- [Upload Service](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/services/upload.service.ts): business service · File upload and storage coordination · `src/services/upload.service.ts`
- [AI Client](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/ai/aiClient.ts): LLM integration · Central model/provider call wrapper · `src/ai/aiClient.ts`
- [Resume AI](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/ai/resumeAnalyzer.ts): AI module · Resume screening and quality analysis · `src/ai/resumeAnalyzer.ts`
- [Ranker](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/ai/candidateRanker.ts): AI module · Candidate scoring and ranking logic · `src/ai/candidateRanker.ts`
- [JD Generator](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/ai/jdGenerator.ts): AI module · Job description generation · `src/ai/jdGenerator.ts`
- [Coach](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/ai/interviewCoach.ts): AI module · Interview coaching and guidance · `src/ai/interviewCoach.ts`

### Infrastructure

Persistence, storage, and external integrations

- [Prisma](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/lib/prisma.ts): database client · Typed PostgreSQL access layer · `src/lib/prisma.ts`
- [Cloudinary](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/lib/cloudinary.ts): storage client · External file storage integration · `src/lib/cloudinary.ts`
- [Redis](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/lib/redis.ts): cache/queue client · Redis connection for async work and caching · `src/lib/redis.ts`
- [Resume Parser](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/lib/resumeParser.ts): document parser · Extracts text from uploaded resumes · `src/lib/resumeParser.ts`

### Async Work

Background queues and Redis-backed jobs

- [Email Queue](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/queues/emailQueue.ts): background queue · Async outbound email jobs · `src/queues/emailQueue.ts`
- [Resume Queue](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/queues/resumeQueue.ts): background queue · Async resume processing jobs · `src/queues/resumeQueue.ts`

### Realtime

Socket channel for live updates

- [Socket](https://github.com/tausif-islam-sheik/hireiq-server/blob/main/src/socket/socket.ts): realtime channel · Live server push and status updates · `src/socket/socket.ts`

## Connections

- Server → Middleware: uses · Bootstrapped HTTP pipeline applies request guards
- Server → Auth Routes: mounts · Express mounts domain routes
- Server → User Routes: mounts · Express mounts domain routes
- Server → Job Routes: mounts · Express mounts domain routes
- Server → App Routes: mounts · Express mounts domain routes
- Server → Company Routes: mounts · Express mounts domain routes
- Server → Resume Routes: mounts · Express mounts domain routes
- Server → Saved Routes: mounts · Express mounts domain routes
- Server → Notify Routes: mounts · Express mounts domain routes
- Server → AI Routes: mounts · Express mounts domain routes
- Auth Routes → Auth Ctrl: calls · Route handlers delegate to controllers
- Job Routes → Job Ctrl: calls · Route handlers delegate to controllers
- Resume Routes → Resume Ctrl: calls · Route handlers delegate to controllers
- Notify Routes → Notify Ctrl: calls · Route handlers delegate to controllers
- Auth Ctrl → Auth Service: delegates · Controller orchestration passes into service layer
- Job Ctrl → Job Service: delegates · Controller orchestration passes into service layer
- Resume Ctrl → Upload Service: delegates · Uploads are handled by storage service
- Resume Ctrl → Resume Parser: parses · Uploaded documents are text-extracted before analysis
- Resume Ctrl → Resume Queue: enqueues · Long-running resume work is pushed async
- Notify Ctrl → Notify Service: delegates · Notification controller uses business service
- Auth Service → Prisma: reads/writes · Auth state is persisted in PostgreSQL via Prisma
- Job Service → Prisma: reads/writes · Job domain persistence
- App Service → Prisma: reads/writes · Application workflow persistence
- Notify Service → Prisma: reads/writes · Notification state persistence
- Upload Service → Cloudinary: stores · Files are uploaded to external storage
- Upload Service → Prisma: tracks · Stored file metadata can be persisted
- Resume Parser → Resume AI: feeds · Parsed resume text is analyzed by AI modules
- Resume AI → AI Client: calls · AI modules use central model client
- Ranker → AI Client: calls · AI modules use central model client
- JD Generator → AI Client: calls · AI modules use central model client
- Coach → AI Client: calls · AI modules use central model client
- AI Routes → AI Client: exposes · AI endpoints surface model-backed features
- Email Queue → Redis: backed by · Queue storage and delivery coordination
- Resume Queue → Redis: backed by · Queue storage and delivery coordination
- Notify Service → Socket: broadcasts · Notification updates may be pushed live
- Notify Service → Email Queue: queues · Outbound email delivery is asynchronous
- Resume Ctrl → Socket: updates · Resume processing status can be broadcast live