Full-Stack Ecosystem Documentation

Nezuko Workforce Platform

An end-to-end HR SaaS ecosystem spanning employee lifecycle management, talent acquisition, and a candidate recruitment portal — engineered across four tightly coupled repositories.

Next.js 16 React 19 TypeScript 5 Tailwind v4 Express 5 PostgreSQL 16 Prisma 7 MongoDB React Query 5 Zustand 5
01

Four Repositories, One Ecosystem

HR Dashboard · Next.js
Nezuko

End-to-end HR SaaS for workforce management — employees, attendance, assets, insurance, leave, projects, reports, and an AI chatbot assistant.

Next.js 16 App Router React Query Zustand next-intl Recharts
Candidate Portal · Vite + React
Portal

Candidate-facing recruitment portal with multilingual job discovery, application tracking, profile management, and a dark-space aesthetic built on Vite.

Vite React Zustand Axios Zod RTL/LTR
Backend API · Node.js
Portal Api

Multi-tenant talent acquisition gateway powering both frontends — RESTful, session-secured, with Cloudinary media streaming, cron jobs, and full RBAC.

Express MongoDB Passport.js Cloudinary Swagger Jest
Backend HR API · Express + PostgreSQL
Nezuko API

Backend REST API powering the HR platform — employee administration, attendance tracking, asset lifecycle, insurance plans, payroll with incentives, dynamic reporting, and an AI chatbot assistant.

Express 5 TypeScript 5 PostgreSQL 16 Prisma 7 JWT Joi 18 Cloudinary Nodemailer Gemini AI PDFKit Docker Compose
02

Tech Stack

Layer Technologies
FrameworkNext.js 16 (App Router) · React 19 · TypeScript 5 · Vite (Portal)
StylingTailwind CSS v4 · clsx · tailwind-merge · custom CSS variables
Client StateZustand 5 — auth store, modal/UI stores, session persistence
Server StateTanStack React Query 5 — 60s stale time, 1 retry, optimistic mutations
HTTPAxios 1 — custom interceptors, token refresh queue, normalized responses
FormsReact Hook Form 7 + Zod 4 — declarative validation, localized error messages
ChartsRecharts — pie, bar, radial bar, animated skeletons
AnimationsFramer Motion 12 — page transitions, staggered reveals
i18nnext-intl 4 — English + Arabic, 20 namespace files, RTL/LTR DOM toggling
Backend (Portal)Express · MongoDB (Mongoose) · Passport (Local + Google + GitHub OAuth)
Nezuko APIExpress 5 · TypeScript 5 · PostgreSQL 16 · Prisma 7 · JWT (httpOnly + Bearer) · Joi 18 · Cloudinary · Nodemailer · Google Gemini · PDFKit · Docker Compose
MediaCloudinary CDN — diskless buffer streaming via streamifier + Multer memory
SecurityHelmet · CORS whitelist · express-rate-limit · signed sessions · httpOnly cookies
Jobsnode-cron — automatic job expiration daemon
Docsswagger-jsdoc + swagger-ui-express — interactive sandbox at /api-docs
TestingJest + Supertest — integration suite
03

Nezuko — HR Module Features

📊
Dashboard
/dashboard
KPIs · Pie/Bar/Radial charts · Overdue tasks
👥
Employees
/employees · /employees/[id]
Full lifecycle CRUD · Role & department assignment
🏢
Company
/company
Info · Settings · Attendance config · Geofence
👤
Profile
/profile
Self-service · Emergency contacts · Role badge
💼
Jobs
/jobs · BFF Proxy
External recruitment · Bilingual EN/AR content
🖥️
Assets
/asset · /asset/[id]
Lifecycle · Custody trail · Depreciation report
🛡️
Insurance
/insurance
BASIC/STANDARD/PREMIUM plans · Dependents
🏖️
Leave
/leave
Submit · Approve/Reject · Cancel workflow
📍
Attendance
/attendance
GPS check-in/out · Geofence validation
⏱️
Timesheets
/timesheets
Multi-entry · Approval workflow · Overtime report
📁
Projects
/projects · /projects/[id]
Tasks · Subtasks · Priority · Progress tracking
📋
Reports
/reports
5 types · CSV/PDF export · History
🌲
Departments
/departments
Recursive tree · Manager assignment
🤖
AI Chatbot
/chatbot
HR assistant · Markdown rendering · Persistent session
...
And more..
Payroll · Pricing · Booking Demo · Services · Blogs · more in dev
04

Authentication & Authorization

Nezuko HR Login Flow
InputcompanyEmail + userEmail + password
→
POST/auth/login
→
localStoragerole · isAuthenticated
→
ZustandAuth Store hydration
→
GuardAuthGuard → route
Refresh tokens are httpOnly cookies — silently refreshed by the Axios interceptor on 401, queuing concurrent requests until renewed.
TENANT_OWNER
Full system access · Company settings · All modules
HR_ADMIN
All HR modules · Jobs · Reports · Department management
MANAGER
Approve leave/timesheets · View team assets · Projects
EMPLOYEE
Profile · Own leave · GPS check-in · Chatbot
05

Internationalization

English
LTR · NEXT_LOCALE cookie · localePrefix: 'never'
commonlandingauth dashboardassetsleave departmentsemployeesinsurance reportstimesheetcompany projectsjobschatbot profilebookDemopricing servicesblogs
العربية
RTL · dir toggled on <html> · same 20 namespaces
مشتركهبوطتسجيل لوحةأصولإجازة أقسامموظفونتأمين تقاريردوامشركة مشاريعوظائفمساعد ملفعرضأسعار خدماتمدونة
06

Portal API — Endpoints

Authentication
POST/auth/signupPublic
POST/auth/loginPublic · rate-limited
GET/auth/logoutPublic
POST/auth/refresh-tokenPublic
GET/auth/googleOAuth
GET/auth/githubOAuth
User Profile
GET/user/meAuthenticated
PATCH/user/avatarAuthenticated
PATCH/user/cvAuthenticated
Job Listings
GET/jobPublic
GET/job/:idPublic
POST/jobAdmin
PATCH/job/:idAdmin
DELETE/job/:idAdmin
PATCH/job/toggle-activation/:idAdmin
Job Applications
POST/job-application/apply/:jobIdCandidate
GET/job-application/my-applicationsCandidate
DELETE/job-application/my-applications/:idCandidate
GET/job-application/admin/allAdmin
PATCH/job-application/admin/:id/statusAdmin
Categories · Experience · Keywords · Countries · FAQs · Contact
GET/category · /experience · /keyword · /country · /faqPublic
POST/category · /experience · /keyword · /country · /faqAdmin
POST/contactusPublic
GET/contactusAdmin
07

Nezuko API — Endpoints

Backend REST API powering the Nezuko HR platform — layered module architecture with JWT authentication and RBAC. All endpoints are prefixed with /api/v1.
Authentication
POST/auth/loginPublic
POST/auth/logoutPublic
GET/auth/meAuthenticated
Dashboard · TENANT_OWNER · HR_ADMIN · MANAGER
GET/dashboard/overviewKPI overview
GET/dashboard/metrics/summaryAggregated KPIs
GET/dashboard/insightsBI insights
GET/dashboard/chartChart data
GET/dashboard/exportExport data
Employee · TENANT_OWNER · HR_ADMIN
GET/employeeList (paginated)
GET/employee/:idDetail
POST/employeeCreate
PATCH/employee/:idUpdate
DELETE/employee/:idDelete
POST/employee/:id/documentsUpload doc
DELETE/employee/:id/documents/:docIdDelete doc
Department · All (view) · HR_ADMIN (mutate)
GET/departmentTree list
GET/department/:idDetail
POST/departmentCreate
PATCH/department/:idUpdate
DELETE/department/:idDelete
Company · All (view) · HR_ADMIN (mutate)
GET/companySettings
PATCH/companyUpdate
POST/company/logoUpload logo
DELETE/company/logoDelete logo
Leave Requests · EMPLOYEE (submit/cancel) · HR_ADMIN/MANAGER (review)
POST/leave-requestsSubmit
GET/leave-requestsList
GET/leave-requests/:idDetail
PATCH/leave-requests/:id/reviewApprove/reject
DELETE/leave-requests/:idCancel
Attendance · EMPLOYEE (check-in/out) · HR_ADMIN/MANAGER (view all)
POST/attendance/check-inGPS check-in
POST/attendance/check-outCheck-out
GET/attendance/timesheetAll timesheets
GET/attendance/mePersonal history
Timesheets · HR_ADMIN (manage) · MANAGER (approve)
POST/timesheetsCreate entry
GET/timesheetsList
PATCH/timesheets/:idEdit
PATCH/timesheets/:id/reviewApprove/reject
GET/timesheets/meMy submissions
GET/timesheets/report/overtimeOvertime report
Asset · HR_ADMIN (manage) · EMPLOYEE (view own)
POST/assetRegister
GET/assetList
GET/asset/:idDetail
PATCH/asset/:idUpdate
POST/asset/:id/assignAssign
POST/asset/:id/returnReturn
GET/asset/meMy assets
GET/asset/employee/:idBy employee
Insurance · HR_ADMIN (manage) · EMPLOYEE (view own)
GET/insurance-plansList plans
POST/insurance-plansCreate plan
PATCH/insurance-plans/:idUpdate plan
DELETE/insurance-plans/:idDelete plan
POST/insurance-enrollmentsEnroll
GET/insurance-enrollmentsList enrollments
GET/insurance-enrollments/meMy enrollments
GET/insurance-enrollments/previewCost preview
Project & Tasks · HR_ADMIN · MANAGER · EMPLOYEE (assignee)
POST/projectCreate project
GET/projectList
GET/project/:idDetail
PATCH/project/:idUpdate
DELETE/project/:idDelete
POST/project/:id/tasksAdd task
GET/tasks/myMy tasks
GET/tasks/overdueOverdue report
Payroll · TENANT_OWNER · HR_ADMIN
POST/payrollsCreate run
GET/payrollsList runs
GET/payrolls/:idDetail
PATCH/payrolls/:id/statusDRAFT→APPROVED→PAID
POST/payrolls/:id/incentivesAdd incentives
GET/payrolls/:id/payslipPDF payslip
GET/payrolls/summarySummary report
Reports · HR_ADMIN · MANAGER
GET/reportsTypes + history
POST/reports/previewPreview data
POST/reports/export/csvExport CSV
POST/reports/export/pdfExport PDF
GET/reports/historyPrevious reports
POST/chatbot/messageAI message
GET/chatbot/sessionsList sessions
GET/chatbot/sessions/:id/messagesSession history
POST/booking-demo-requestPublic
08

Backend Architecture & Patterns

Every feature follows a consistent layered module structure with strict separation of concerns.
feature/ ├── routes.ts # Route definitions with middleware chain ├── controller.ts # Request/response handling, calls service ├── service.ts # Business logic layer └── repository.ts # Prisma database queries // Middleware chain per route route → requireAuth // JWT cookie/Bearer → req.user → checkRole([...]) // RBAC authorization → validate(schema) // Joi schema → controller // business logic → globalErrorHandler // i18n-aware error response
Key Decisions
  • Multi-tenant isolation via tenantId on every model
  • JWT dual-mode: httpOnly cookie + Bearer header
  • 18 custom error classes (400–504), i18n-aware
  • Consistent response: { status, message, data?, errors?, code? }
Project Structure
  • prisma/ — Schema + migrations
  • src/locales/ — en.json + ar.json (614+ lines)
  • src/modules/ — 15 feature modules
  • src/shared/ — config, middleware, errors, interfaces, enums, services, utils, validations
09

Frontend HTTP Layer Architecture

// Axios interceptor chain — Nezuko HR axios instance (withCredentials: true, baseURL from env) → request interceptor // extensible, locale headers → response interceptor // normalize { data, error, status, all } // on 401: queue concurrent requests → POST /auth/refresh → retry → request wrappers // getRequest / postRequest / patchRequest / deleteRequest / uploadRequest → throwIfError() // converts error response → thrown Error // Feature module pattern feature/ ├── api/feature.api.ts // axios wrappers + throwIfError ├── hooks/useFeature.ts // React Query useQuery / useMutation ├── types/feature.dto.ts // Zod validation schemas ├── mappers/feature.mapper.ts // DTO → frontend model └── _components/ // colocated UI components