Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Rampop01/HR-Platform/llms.txt

Use this file to discover all available pages before exploring further.

​
Quickstart Guide

This guide will help you get HCMatrix running locally in under 5 minutes. You’ll set up the development environment, configure the backend connection, and log in to the dashboard.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 18.x or higher installed
  • npm or yarn package manager
  • A terminal/command line interface
  • A code editor (VS Code recommended)

​
Quick Setup

1

Clone the repository

git clone <repository-url>
cd hcmatrix
2

Install dependencies

Install all required packages using npm:
npm install
This will install all dependencies from package.json:11, including:
  • Next.js 16.1.6
  • React 19.2.4
  • TypeScript 5.7.3
  • Tailwind CSS 4.2.0
  • Radix UI components
  • Recharts for data visualization
3

Configure environment

Create a .env.local file in the root directory:
touch .env.local
Add your backend API URL:
NEXT_PUBLIC_API_URL=https://your-backend-api.com
The API proxy is configured to route requests through /api/proxy to avoid CORS issues. See lib/api.ts:2 for implementation details.
4

Start the development server

Run the development server:
npm run dev
The application will start on http://localhost:3000
The dev server supports hot module replacement, so changes to your code will be reflected immediately in the browser.
5

Access the application

Open your browser and navigate to:
http://localhost:3000
You’ll be automatically redirected to the login page at /auth/login.

​
Your First Login

The login page provides a clean, professional interface for authentication.

​
Login Form

From app/auth/login/page.tsx:19, here’s how the login process works: 
const handleLogin = async (e: React.FormEvent) => {
  e.preventDefault()
  setError('')
  setIsLoading(true)

  try {
    const response = await api.login(email, password)
    auth.saveSession({
      token: response.token,
      user: response.user,
    })
    router.push('/dashboard')
  } catch (err) {
    setError(err instanceof Error ? err.message : 'Login failed')
  } finally {
    setIsLoading(false)
  }
}

​
Login Interface

1

Enter your credentials

  • Email: Your organization email address
  • Password: Your secure password
2

Sign in

Click the “Sign In” button. The system will:
  1. Call the /api/auth/login endpoint
  2. Receive a JWT token and user data
  3. Store the session in localStorage (see lib/auth.ts:13)
  4. Redirect you to the dashboard
If you don’t have credentials, contact your system administrator. The platform does not support self-registration - accounts must be created by administrators.

​
Exploring the Dashboard

Once logged in, you’ll see the main dashboard with:

​
Key Metrics

From app/dashboard/page.tsx:12, the dashboard displays:
  • Total Employees: Current workforce count with growth percentage
  • New Hires This Month: Recent onboarding activity
  • Upcoming Events: Birthdays, anniversaries, and important dates
  • Open Positions: Active job requisitions

​
API Integration Example

useEffect(() => {
  const token = auth.getToken()
  if (!token) {
    router.push('/auth/login')
    return
  }

  const fetchDashboard = async () => {
    try {
      const data = await api.getDashboard(token)
      setDashboardData(data)
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Failed to load dashboard')
    } finally {
      setIsLoading(false)
    }
  }

  fetchDashboard()
}, [router])

​
Visual Analytics

The dashboard includes:
  1. Headcount Growth Chart: 7-month trend visualization using Recharts
  2. Department Distribution: Pie chart showing workforce breakdown
  3. Attendance Metrics: Real-time presence tracking
  4. Action Items: Pending tasks requiring attention

​
Managing Employees

Navigate to the Employees section to view your workforce.

​
Employee List

From app/employees/page.tsx:25, the employee directory supports: 
const fetchEmployees = useCallback(async (page: number = 1, query: string = '') => {
  const token = auth.getToken()
  if (!token) {
    router.push('/auth/login')
    return
  }

  setIsLoading(true)
  try {
    let response: EmployeesResponse
    if (query.trim()) {
      response = await api.searchEmployees(token, { name: query.trim() }, page)
    } else {
      response = await api.getEmployees(token, page)
    }
    setEmployees(response.data)
    setPagination({ /* pagination data */ })
  } catch (err) {
    setError(err instanceof Error ? err.message : 'Failed to load employees')
  }
}, [router])

​
Features

Search

Real-time search with 500ms debounce for optimal performance

Pagination

Server-side pagination with customizable page size

Status Badges

Visual indicators for Active, Onboarding, On Leave, and other statuses

Quick View

Click any employee to view detailed profile information

​
Understanding the API Client

HCMatrix uses a typed API client defined in lib/api.ts. Here are the main methods:

​
Authentication

// Login
await api.login(email: string, password: string): Promise<LoginResponse>

// Logout
await api.logout(token: string): Promise<void>

​
Data Fetching

// Get dashboard data
await api.getDashboard(token: string): Promise<DashboardData>

// Get paginated employees
await api.getEmployees(token: string, page?: number): Promise<EmployeesResponse>

// Get single employee
await api.getEmployee(token: string, id: number): Promise<EmployeeDetail>

// Search employees
await api.searchEmployees(
  token: string, 
  query: Record<string, string>, 
  page?: number
): Promise<EmployeesResponse>

​
TypeScript Interfaces

All API responses are fully typed. From lib/api.ts:19: 
export interface DashboardData {
  total_employees: number
  new_hire_count: number
  upcoming_event: number
  open_positions: number
}

export interface Employee {
  id: number
  name: string
  email: string
  job_title: string
  department: string
  location: string
  employment_type: string
  status: string
  start_date: string
  avatar?: string
}

export interface EmployeeDetail extends Employee {
  phone: string
  date_of_birth: string
  address: string
  salary: number
  manager: string
  manager_id: number
  next_of_kin_name: string
  next_of_kin_relationship: string
  next_of_kin_phone: string
  tenure_years: number
  tenure_months: number
  spouse: string | null
}

​
Next Steps

Full Installation Guide

Learn about production deployment, environment variables, and advanced configuration

API Reference

Explore all available API endpoints and their usage

​
Troubleshooting

  • Verify your backend API URL in .env.local
  • Check that the backend service is running
  • Ensure CORS is properly configured on the backend
  • Check the browser console for detailed error messages
  • Verify your authentication token is valid
  • Check network requests in browser DevTools
  • Ensure the backend API endpoints are accessible
  • Clear localStorage and login again
  • Ensure Node.js version is 18.x or higher
  • Delete node_modules and package-lock.json, then run npm install again
  • Check for conflicting global packages
If you encounter issues not covered here, check the browser console and terminal output for detailed error messages.

Build docs developers (and LLMs) love

Get started for freeTalk to us