Employee Management

Employee Profiles

Every team member gets a rich profile that captures their personal details, role information, location, and employment history. Profiles are the foundation for compensation, skills tracking, and document management.

Creating an Employee Record

Employee creation uses a multi-step form that guides you through each section of the profile. Steps are validated individually so you can catch issues before submitting.

1. Navigate to Employees from the sidebar and click Add Employee.
2. Step 1 - Personal Info: Enter the employee's first name, last name, date of birth, and upload a profile image.
3. Step 2 - Contact: Provide the employee's email address, phone number, and emergency phone number.
4. Step 3 - Employment: Set the job title, job level (seniority), hire date, salary, compensation type, salary currency, pay day, pay day of week, and semi-monthly pay days.
5. Step 4 - Skills & Documents: Tag the employee with skills, upload documents (PDFs are automatically text-extracted), and set the employee's location.

Key Profile Fields

• Name - Full name displayed across the platform
• Email - Clickable mailto link in the employee drawer
• Phone - Formatted with international dialing code
• Emergency Phone - Secondary contact number for emergencies
• Date of Birth - The system auto-calculates the employee's age from this field
• Position - Job title (e.g., Senior Developer, Account Manager)
• Job Level - Seniority level (e.g., Junior, Mid, Senior, Lead), shown in the hero section of the employee drawer
• Location - Employee location or office
• Hire Date - Used for tenure calculations and onboarding timelines
• Status - Active or Terminated; use the status filter on the employee list to quickly isolate active or terminated employees

Viewing Employee Details

Click any employee row to open the entity drawer. The drawer uses a hero header layout showing the employee's name, position, and status badge at a glance. Below the header, grouped sections display contact information, role details, compensation, recent payments, skills, and uploaded documents.

Editing Employee Information

From the employee drawer or the row actions menu, click Edit to open the same multi-step form pre-filled with existing data. Changes are saved immediately on submit and reflected across all linked records.

Employee List

The employee table supports full-text search, column filters, and a column visibility toggle so you can customize which fields are shown. Use the status filter to quickly isolate active employees, or sort by department to see your team structure at a glance.

Setting an Employee's Location

In Step 4 of the employee creation form, you can set a precise geographic location for each team member. Click the Open Location Search button to launch the interactive location picker. There are three ways to set a location:

1. Text search - Type a city name, street address, or landmark into the search field. The system uses Nominatim geocoding to resolve the query and returns a full address including city, country, and street details.
2. Coordinates - Enter latitude and longitude values directly, then click Find Location to place the pin at those exact coordinates.
3. Click the map - Click anywhere on the interactive map to drop a pin at that position. The resolved address updates automatically based on where you click.

The map defaults to a Beirut-centered view when no location has been set. Once saved, the employee's detail drawer displays a read-only map with the pinned location, giving you a quick visual reference without needing to open the edit form.

Compensation and Payments

Belvak supports flexible compensation tracking with four pay schedules, multi-currency salaries, and automated payment generation. Each payment is a full entity with its own status lifecycle, making it easy to track what has been paid and what is outstanding.

Compensation Types

When setting up an employee's compensation, choose one of four supported pay schedules:

• Monthly Salary - One payment per month on the configured pay day
• Weekly - Payment generated every week on the configured day of the week (pay_day_of_week)
• Bi-weekly - Payment generated every two weeks on the configured day of the week (pay_day_of_week)
• Semi-monthly - Two payments per month on two configured pay days (pay_day_semi_1 and pay_day_semi_2, e.g., the 1st and 15th)
• Per-Work - For freelancers and contractors who are paid per task or deliverable. Per-Work employees are not included in automatic payment generation; their payments must be created manually

Salary Currency

Each employee's salary is stored in a specific ISO 4217 currency code. The default is USD, but you can select any currency enabled in your system settings. The currency is carried forward to all generated payments so amounts display correctly.

Pay Day Configuration

Pay day settings depend on the compensation type:

• Monthly Salary - Set pay_day to a value between 1 and 28. The upper limit of 28 ensures consistent behavior across all months, including February.
• Weekly / Bi-weekly - Set pay_day_of_week to the desired day of the week (e.g., Monday, Friday).
• Semi-monthly - Set pay_day_semi_1 and pay_day_semi_2 to the two days of the month when payments should be generated (e.g., 1 and 15).

Row Actions

The employee table provides quick status-change actions through the three-dot menu or right-click context menu on each row:

• Terminate - Shown for active employees. Marks the employee as terminated.
• Activate - Shown for non-active employees. Restores the employee to active status.

Process Payments

At the top of the Employees page, a Process Payments header action button allows you to manually trigger payment generation for all eligible employees on demand. This is useful when you need to generate payments outside of the daily automated schedule. The button requires employee edit permission.

Employee Payments

The Employee Payments entity provides full CRUD for individual payment records. Each payment tracks the employee, amount, currency, period, and status.

Payment Statuses

• Pending - Payment has been generated but not yet processed
• Paid - Payment has been completed; the paid date is automatically set when you mark a payment as paid
• Cancelled - Payment was voided and will not be processed

Change a payment's status using the row actions menu in the payments table. When you mark a payment as Paid, the system automatically records the current date as the paid date.

Bulk Actions

Each row in the Employee Payments table has a checkbox for selection. When you select one or more rows, a floating action bar appears at the bottom of the screen showing the count of selected records and the available actions. This is the same table interaction pattern used across other entities in the platform.

Five bulk actions are available:

• Mark as Paid - Changes all selected payments to "paid" status and records the current date as the paid date
• Cancel - Changes all selected payments to "cancelled" status
• Revert to Pending - Reverts selected payments back to "pending" status, useful if a payment was marked incorrectly
• Export PDF - Generates a PDF report containing only the selected payments (see Exporting Payment Reports below)
• Delete - Permanently removes the selected payment records from the system

All destructive actions, including status changes and deletion, display a confirmation dialog before executing. This follows the same activity logging pattern used elsewhere in the platform, so every bulk status change is recorded. Nothing is applied until you confirm.

Exporting Payment Reports

There are two ways to export employee payment data as a PDF report:

1. Export Pending PDF button - Located in the Employee Payments page header, this one-click action exports all payments that currently have "pending" status. No row selection is needed.
2. Bulk action Export PDF - Select specific rows first using the checkboxes, then click Export PDF in the floating action bar. This exports only the selected payments regardless of their status.

The generated PDF is in A4 landscape format and includes the following columns for each payment: employee name, phone number, amount, due date, period, compensation type, and payment method. At the bottom of the report, a summary section shows totals grouped by currency, which is especially useful for teams that pay employees in multiple currencies.

Unlike invoice PDF exports which are client-facing and follow customizable templates, payment reports are internal documents designed for payroll processing and record keeping.

Automated Payment Generation

A daily automated job runs at 9 AM and generates pending payment records for all active employees with a configured compensation type. The process is idempotent: it checks the period month and year before creating a record, so running it multiple times will never produce duplicates.

Recent Payments in the Employee Drawer

When viewing an employee's profile, the drawer includes a "Recent Payments" section that shows the last 5 payments with their status and amounts. Click View All to navigate to the full Employee Payments table filtered to that employee.

Skills Tracking

Maintain a clear picture of your team's capabilities by tagging employees with skills. This makes it straightforward to find the right person for a project or identify gaps in your team's expertise.

Adding Skills to Employees

Skills are managed in Step 4 (Skills & Documents) of the employee form. During creation or editing, you can select from existing skills in your system or add new ones. Skills come from a global skills library that is shared across both Employees and Seekers, so the same skill definitions are reused throughout the platform. Each skill assignment is stored as a relationship between the employee and the skill, allowing the same skill to be shared across multiple team members.

Step 4 also handles document uploads. When PDF documents are uploaded, the system automatically extracts the text content for search and reference purposes.

Team Composition and Project Assignment

When assembling a project team, use skills data to make informed assignment decisions. Filter or search employees by specific skills to quickly identify who has the expertise a project requires. This is especially valuable for service companies that staff projects with specialized roles.

Searching by Skill

The employee list supports searching across skills, so typing a technology name or certification will surface all employees who have that skill assigned. This makes resource planning faster when you need to staff a new engagement.

Employee Documents

Store employment contracts, identification documents, certifications, and other files directly on each employee's record. All uploads are authenticated, and documents are accessible through the employee drawer. When you upload a PDF or DOCX file, the system can automatically extract profile data using AI.

Uploading Documents

There are several ways to attach files to an employee record:

• Drag and drop - Open the employee's detail drawer and drag a file anywhere onto it. A full-drawer overlay appears and the file is saved automatically.
• Click to browse - In the documents section of the detail drawer, click the "click to browse" link to select files from your device.
• Edit form - Click Edit, navigate to the Skills & Documents step, and use the upload field.

Image files (JPG, PNG) are automatically routed to the profile image field, while document files (PDF, DOC) go to the documents field. Supported formats: PDF, DOC, DOCX, JPG, JPEG, PNG, GIF, WEBP - up to 5 MB per file.

Viewing Documents

Documents are listed in the employee drawer as file cards showing the file name, type icon, and file size. Click a document to preview it in the browser, or use the download button to save it locally.

Deleting Documents

To prevent accidental data loss, document deletion requires a double confirmation. You can initiate deletion from either the view drawer or the edit drawer - both paths present a confirmation dialog before permanently removing the file from the server.

PDF and Document Auto-Extraction

When you upload the first PDF or DOCX file during the Skills and Documents step, the system automatically extracts text from the document and uses AI to populate profile fields. This is especially useful when onboarding new team members from their resumes or CVs.

The following fields are auto-filled when extraction succeeds:

• First name and last name
• Date of birth
• Email address and phone number
• Job title and job level
• LinkedIn URL
• Skills

After you upload the file, an "Extracting Data from PDF..." loading indicator appears while the system processes the document. Once complete, a success or error notification is shown and the form fields update automatically with the extracted values. This extraction only triggers on the first document upload; subsequent uploads to the same record do not re-run extraction.

Extraction works best with well-structured, text-based PDF and DOCX files. Scanned images or heavily formatted documents may produce incomplete results. The same auto-extraction feature is available when uploading CVs for job seekers in the recruitment module.