Quickstart

Get HCMatrix up and running in under 5 minutes

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

Login fails with 'API error'

• 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

Dashboard shows no data

• Verify your authentication token is valid
• Check network requests in browser DevTools
• Ensure the backend API endpoints are accessible
• Clear localStorage and login again

Build errors during npm install

• 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.