Backend Controllers

Controllers handle HTTP requests, validate input, call services, and return standardized responses. Located in /src/controllers/.

AuthController

File: auth.controller.ts

Handles authentication and registration endpoints.

Endpoints Handled

Endpoint	Handler	Description
POST /auth/send-verification-code	sendVerificationCode	Send SMS OTP
POST /auth/verify-code	verifyCode	Verify OTP, get token
POST /auth/resend-code	resendCode	Resend OTP
POST /auth/register/user	registerUser	Complete user registration
POST /auth/register/employer	registerEmployer	Complete employer registration
POST /auth/login/user	loginUser	User login
POST /auth/login/employer	loginEmployer	Employer login
POST /auth/refresh	refreshToken	Refresh JWT tokens
POST /auth/logout	logout	Clear refresh token

Validation Schemas

export const sendVerificationCodeSchema = Joi.object({
  phone: Joi.string().required().pattern(/^\+[1-9]\d{1,14}$/),
  userType: Joi.string().valid('user', 'employer').required(),
});

export const registerUserSchema = Joi.object({
  verificationToken: Joi.string().required(),
  name: Joi.string().required().trim(),
  email: Joi.string().email().optional(),
  password: Joi.string().min(6).required(),
  location: Joi.string().required(),
  bio: Joi.string().optional(),
  role: Joi.string().valid('job_seeker', 'service_worker', 'client', 'hybrid').optional(),
});

export const loginUserSchema = Joi.object({
  phone: Joi.string().required(),
  password: Joi.string().required(),
});

---

JobController

File: job.controller.ts

Handles job listing CRUD operations.

Endpoints Handled

Endpoint	Handler	Description
GET /jobs	getJobs	List jobs (paginated)
GET /jobs/search	searchJobs	Full-text search
GET /jobs/:id	getJob	Get single job
POST /jobs	createJob	Create job (employer auth)
PUT /jobs/:id	updateJob	Update job (employer auth)
DELETE /jobs/:id	deleteJob	Delete job (employer auth)

Validation Schemas

export const createJobSchema = Joi.object({
  title: Joi.string().required().trim(),
  company: Joi.string().required().trim(),
  location: Joi.string().required(),
  salary: Joi.number().required().min(0),
  currency: Joi.string().default('USD'),
  description: Joi.string().required(),
  requirements: Joi.array().items(Joi.string()).default([]),
  benefits: Joi.array().items(Joi.string()).default([]),
  jobType: Joi.string().valid('full_time', 'part_time', 'contract', 'internship', 'remote').required(),
  experienceLevel: Joi.string().valid('entry', 'mid', 'senior', 'executive').required(),
  hashtags: Joi.array().items(Joi.string()).default([]),
  email: Joi.string().email().required(),
  whatsappContact: Joi.string().optional(),
  expiryDate: Joi.date().required(),
  aiInterviewEnabled: Joi.boolean().default(false),
  autoInviteOnApply: Joi.boolean().default(false),
  interviewQuestions: Joi.number().min(5).max(20).default(10),
  interviewTimeLimit: Joi.number().min(5).max(60).default(15),
});

---

ApplicationController

File: application.controller.ts

Handles job applications.

Endpoints Handled

Endpoint	Handler	Description
POST /applications	createApplication	Submit application
GET /applications/user	getUserApplications	User's applications
GET /applications/employer	getEmployerApplications	Employer's received apps
GET /applications/:id	getApplication	Get single application
PATCH /applications/:id/status	updateApplicationStatus	Change status
DELETE /applications/:id	deleteApplication	Withdraw application

---

UserController

File: user.controller.ts

Handles user profiles and related operations.

Endpoints Handled

Endpoint	Handler	Description
GET /users/me	getCurrentUser	Get authenticated user
PUT /users/me	updateCurrentUser	Update profile
POST /users/swipe	addSwipeHistory	Record job swipe
POST /users/save/:jobId	saveJob	Save job
DELETE /users/save/:jobId	unsaveJob	Unsave job
GET /users/saved	getSavedJobs	Get saved jobs
GET /users/profile-completeness	getProfileCompleteness	Check profile completion
POST /users/education	addEducation	Add education
PUT /users/education/:id	updateEducation	Update education
DELETE /users/education/:id	deleteEducation	Delete education
POST /users/experience	addExperience	Add experience
PUT /users/experience/:id	updateExperience	Update experience
DELETE /users/experience/:id	deleteExperience	Delete experience

---

ServicesController

File: services.controller.ts

Handles service worker profiles and discovery.

Endpoints Handled

Endpoint	Handler	Description
POST /services/worker	createWorkerProfile	Create worker profile
GET /services/worker/me	getMyWorkerProfile	Get my worker profile
PUT /services/worker/me	updateWorkerProfile	Update profile
PATCH /services/worker/availability	toggleAvailability	Toggle availability
GET /services/workers/nearby	getNearbyWorkers	GPS-based search
GET /services/workers/feed	getWorkerFeed	TikTok-style feed
POST /services/workers/:id/swipe	swipeWorker	Swipe on worker
GET /services/workers/:id/likes	getWorkerLikes	Who liked worker
GET /services/categories	getCategories	List categories
POST /services/categories	createCategory	Create category
GET /services/workers/search	searchWorkers	Search workers

---

BookingsController

File: bookings.controller.ts

Handles service requests, quotes, and bookings.

Endpoints Handled

Endpoint	Handler	Description
POST /bookings/requests	createRequest	Post service request
GET /bookings/requests/mine	getMyRequests	Client's requests
GET /bookings/requests/nearby	getNearbyRequests	Requests near worker
GET /bookings/requests/:id	getRequest	Get request details
PATCH /bookings/requests/:id/status	updateRequestStatus	Update status
POST /bookings/requests/:id/swipe	swipeRequest	Worker swipes on request
POST /bookings/quotes	createQuote	Submit quote
GET /bookings/requests/:id/quotes	getQuotes	Get quotes for request
POST /bookings/quotes/:id/accept	acceptQuote	Accept quote
POST /bookings/quotes/:id/reject	rejectQuote	Reject quote
POST /bookings	createBooking	Direct booking
GET /bookings/client	getClientBookings	Client's bookings
GET /bookings/worker	getWorkerBookings	Worker's bookings
GET /bookings/:id	getBooking	Get booking details
PATCH /bookings/:id/status	updateBookingStatus	Update status

---

MessagesController

File: messages.controller.ts

Handles messaging between users.

Endpoints Handled

Endpoint	Handler	Description
GET /messages/conversations	getConversations	List conversations
GET /messages/conversations/:id	getConversation	Get with messages
GET /messages/conversations/:id/messages	getMessages	Paginated messages
POST /messages/conversations/:id/messages	sendMessage	Send message
POST /messages/conversations/:id/read	markAsRead	Mark as read
DELETE /messages/:messageId	deleteMessage	Delete message
POST /messages/conversations/:id/typing	updateTypingStatus	Update typing
GET /messages/conversations/:id/typing	getTypingUsers	Get typing users
POST /messages/conversations/:id/pin	togglePin	Toggle pin
POST /messages/conversations/:id/mute	toggleMute	Toggle mute
POST /messages/conversations/:id/archive	archiveConversation	Archive
POST /messages/conversations/:id/unarchive	unarchiveConversation	Unarchive
GET /messages/unread-count	getUnreadCount	Total unread

---

CreditsController

File: credits.controller.ts

Handles credit wallet operations.

Endpoints Handled

Endpoint	Handler	Description
GET /credits/balance	getBalance	Get credit balance
GET /credits/transactions	getTransactions	Transaction history
GET /credits/packages	getPackages	Available packages
GET /credits/currencies	getCurrencies	Supported currencies
GET /credits/payment-methods	getPaymentMethods	Payment options
POST /credits/payment-request	createPaymentRequest	Request to buy credits
POST /credits/payment-request/:id/reference	submitPaymentReference	Submit payment ref
GET /credits/payment-requests	getPaymentRequests	User's requests
POST /credits/cashout	createCashoutRequest	Request cashout
GET /credits/cashout-requests	getCashoutRequests	User's cashout requests

---

BillingController

File: billing.controller.ts

Handles Stripe subscription billing.

Endpoints Handled

Endpoint	Handler	Description
GET /billing/plans	getPlans	Get subscription plans
POST /billing/checkout	createCheckout	Create Stripe checkout
POST /billing/webhook	handleWebhook	Stripe webhook handler
GET /billing/mode	getMode	Get Stripe mode (test/live)

---

InterviewController

File: interview.controller.ts

Handles AI interview integration.

Endpoints Handled

Endpoint	Handler	Description
POST /interviews/create	createSession	Create interview session
GET /interviews/status/:applicationId	getStatus	Get interview status
GET /interviews/pending	getPendingInterviews	User's pending interviews
GET /interviews/all	getAllInterviews	User's all interviews
GET /interviews/session/:applicationId	getSessionForUser	Get session URL
PATCH /interviews/privacy	updatePrivacy	Toggle score visibility
POST /interviews/webhook/completed	handleWebhook	Okia completion webhook

---

ExperienceController

File: experience.controller.ts

Handles Experience Lab operations.

Endpoints Handled

Endpoint	Handler	Description
GET /experience/tracks	getTracks	List all tracks
GET /experience/tracks/:slug	getTrack	Get track by slug
POST /experience/tracks/:id/enroll	enrollInTrack	Enroll in track
GET /experience/enrollments	getEnrollments	User's enrollments
GET /experience/tasks/:id	getTask	Get task details
POST /experience/tasks/:id/submit	submitTask	Submit task answer
GET /experience/progress	getProgress	User's full progress
GET /experience/certificates	getCertificates	User's certificates
GET /experience/verify/:code	verifyCertificate	Verify certificate
GET /experience/leaderboard	getLeaderboard	Top users

---

Common Response Pattern

All controllers use the standardized ApiResponse:

static async getJob(req: Request, res: Response) {
  try {
    const { id } = req.params;
    const job = await JobService.getJobById(id);
    
    if (!job) {
      return ApiResponse.notFound(res, 'Job not found');
    }
    
    ApiResponse.success(res, job, 'Job retrieved successfully');
  } catch (error: any) {
    ApiResponse.serverError(res, error.message, error);
  }
}

Response Format

{
  "success": true,
  "data": { ... },
  "message": "Job retrieved successfully",
  "metadata": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "hasNext": true
  }
}