hrms
One internal HR system that carries a person from job applicant to employee on a single record, then drives their payroll and leave from it. Built for Pakistani payroll rules (CNIC, EOBI, Provident Fund, withholding tax)
- Language
- TypeScript
- Stars
- 0
- Last updated
From the README
WaveTech HRMS
One internal HR system that carries a person from job applicant to employee on a single record, then drives their payroll and leave from it. Built for Pakistani payroll rules (CNIC, EOBI, Provident Fund, withholding tax). The full design is in WaveTech HRMS — System Design.md.
Modules:
- Recruitment – candidates, a drag-and-drop pipeline board, interviews, a contact log with follow-ups, and a hire action that creates the employee
- Employees – the staff register, documents, and activation checks (CNIC and signed contract required)
- Payroll – salary structures with history, monthly runs computed as A + B − C with mid-month proration, loans and advances, CSV and bank files, and printable payslips
- Leave – leave types, a balance ledger, approvals (HR or line manager), and unpaid days that flow into payroll
- Sales – sales credited to closers and fronters (the CRM's compliance-approved sales, or recorded by hand), slab-based incentives that flow into payroll
- Attendance – shift days from the dialer (first and last call, reported by the QA platform), judged present, late, half day or absent by HR's rules; HR can set any day by hand
- Shared core – users and roles, an audit trail, notifications, and self-service for each employee
Run it with Docker
You need Docker Desktop (or Docker Engine with the Compose plugin).
cp .env.example .env # then change POSTGRES_PASSWORD and ADMIN_PASSWORD
docker compose up -d --buildOpen http://localhost:3000 and sign in with ADMIN_EMAIL / ADMIN_PASSWORD from .env. The defaults are admin@wavetech.pk / ChangeMe123!.
To try it with sample people, candidates, leave and 12 months of payroll, set SEED_DEMO=true in .env before the first start. Demo data loads only into an empty database. The demo also creates these sign-ins, all with the password Demo1234!:
| Role | |
|---|---|
| finance@wavetech.pk | Payroll and finance |
| recruiter@wavetech.pk | Recruiter |
| manager@wavetech.pk | Manager (Sales team lead, approves their team's leave) |
| employee@wavetech.pk | Employee self-service |
To start over with an empty database, run docker compose down -v and then docker compose up -d --build. The -v flag deletes all data and uploaded files.
Services
web (nginx :3000) ──/api──▶ api (Fastify :8080) ──▶ postgres (:5432)
- api runs database migrations and the base seed at boot, then serves
/api/v1. It also runs a leave-accrual job every 6 hours. The job is idempotent: each grant carries a unique reference. - web is the static React build. nginx proxies
/apito the api container. - Postgres and the API are published on
127.0.0.1only. Only the web port is meant to be open.
Deploy on Coolify
docker-compose.coolify.yml is the same stack without host ports or a .env file.
- Create the resource. New Resource → Public Repository →
https://github.com/abdulmanan69/hrms, branchmain. - Pick the build. Build Pack Docker Compose, location
/docker-compose.coolify.yml. - Set the domain on the
webservice, for examplehttps://hr.example.com. The domain's DNS must point at the server first, so the HTTPS certificate can be issued. - Set the admin password. In Environment Variables, set
ADMIN_PASSWORD, plusADMIN_EMAIL,COMPANY_NAMEandCOMPANY_SLUGif they differ from the defaults. Coolify generates the database password. - Deploy. After each push to
main, press Redeploy in Coolify. To redeploy on every push instead, add the webhook from the resource's Webhooks page to the GitHub repository.
Remote diagnostics
See inside a running instance from any computer, without SSH or a login: problems, errors, logs, API timing and the database. It stays off until a token is set.
- Make a token. On your computer, in this repository, run
node scripts/ops.mjs init --url https://your-hrms. It writes.ops.local(git ignores it) with a new random token. - Give it to the server. Copy
OPS_TOKENfrom.ops.localto the server (Coolify: Environment Variables; Docker:.env) and redeploy. - Use it. Run
node scripts/ops.mjs status.
| Command | Shows |
|---|---|
status |
API, database, connection pool, requests, webhooks, integrations and background jobs at a glance, a list of problems, every company's counts, recent starts |
errors [--since 24h] [--list] |
warnings and errors grouped by message, with stack traces |
logs [--since 1h] [--grep text] [--level warn] [--follow] |
everything logged, live with --follow |
requests |
API timing per minute and per route, requests slower than 1 s |
db |
connections, running queries, table sizes |
- Logs survive restarts and crashes. They are kept in the
ops_logtable for 14 days. - Secrets are masked before anything is stored: API keys, passwords, tokens, CNIC and account numbers.
- No people's records. The endpoints return only counts, timings and log lines, and there is no SQL endpoint.
- Limit who can call it.
OPS_ALLOWED_IPS(IPs or IPv4 CIDR, comma-separated) restricts access further.
Backups
Uploaded documents are stored compressed inside Postgres, so one dump holds everything:
docker compose exec postgres pg_dump -U hrms -Fc hrms > backup-$(date +%F).dump
Files and PDFs
- Uploads (employee documents, leave attachments) are compressed when they arrive, then stored in the
stored_filestable:- Photos and scans are turned upright, scaled to at most 2,400 px and re-saved as JPEG (or WebP if transparent). A 5 MB phone photo usually becomes 200–400 KB.
- PDF and Word files are compressed with Brotli and come back byte-for-byte identical. A PDF's internals are never rewritten, so a signed contract keeps a valid digital signature. Most PDFs are already compressed inside, so savings vary from a few percent to over 90% for text-only ones.
- A file is refused when its content doesn't match its type, for example a renamed
.exe. - Files left on disk by older versions are moved into the database at the next start.
- Payslip PDFs are never stored. They are generated from the payslip records whenever someone downloads one, either one payslip or a whole run with a page per payslip, so they always match the data.
Develop locally
# database docker run -d --name hrms-dev-db -e POSTGRES_DB=hrms -e POSTGRES_USER=hrms -e POSTGRES_PASSWORD=hrms -p 127.0.0.1:5433:5432 postgres:16-alpine # api (http://localhost:8080) cd server echo "DATABASE_URL=postgres://hrms:hrms@localhost:5433/hrms" > .env echo "SEED_DEMO=true" >> .env npm install npm run dev # web (http://localhost:3000, proxies /api to :8080) cd web npm install npm run dev
Useful scripts:
- server:
npm run typecheck,npm test(payroll engine tests),npm run generate(new migration after a schema change) - web:
npm run typecheck,npm run build
Code map
server/src/
db/schema.ts the whole data model (one file)
db/seed.ts roles, first admin, leave types, departments, settings
db/seedDemo*.ts sample data (SEED_DEMO=true)
auth/ sessions (httpOnly cookie, SHA-256 stored), permissions, guards
lib/ errors, audit + notify, dates, uploads, CSV
services/ shared logic: createEmployee + SIP IDs, leave ledger, payroll engine, settings
routes/ one file per module, mounted under /api/v1
web/src/
components/ui.tsx the UI kit every page uses
components/Layout.tsx sidebar, top bar, notifications
pages/<module>/ pages per module
lib/ api client, auth, formatting
illustrations/ registry.ts (every illustration by name), Illustration.tsx, svg/, LICENSES.md
docs/BUILD_CONTRACT.md conventions and design rules for adding to a module
Connecting other apps
Other systems (web apps, attendance devices, accounting, scripts) connect under Admin → Integrations:
- API keys: read and send data through the same REST API the app uses. Each key works in one company, with only the permissions it was given.
- Webhooks: signed
POSTs to your URL when something happens (new hire, leave approved, payroll paid …). Failed sends are retried for about a day. - Event feed:
GET /api/v1/integrations/events?after=for systems that poll. - WebSocket:
/api/v1/wsfor a live connection. Events stream in, and API requests can go over the same socket.
Full details and examples: docs/INTEGRATIONS.md. Events are written in the same transaction as each change, so none are lost or invented. Payloads never include CNIC, bank details or date of birth.
Companies
One installation serves several companies, and they are kept completely apart: people, SIP IDs, payroll, leave, documents, users, roles, settings, notifications and the audit trail.
- The database enforces it, not just the code.
- Every business row carries
company_id. - Postgres row-level security lets each request see and change only its own company's rows.
- Each API request runs in one short transaction pinned to the signed-in company, as the restricted role
hrms_app. Both settings are transaction-local, so they can never carry over to the next request that reuses the same pooled connection. - Application code that tries to read data outside a company context fails with an error instead of seeing every company.
- Every business row carries
- References can't cross companies. Links between records use composite keys
(company_id, id). So a payslip, leave request, document or manager link can only point at a record of the same company. - SIP IDs are per company. Every company starts at
YYYY-0001. - Super admins (Admin → Companies) add, rename and disable companies, and switch into any company from the company name at the top of the sidebar. Everyone else only ever sees their own company.
- One email in several companies means one account per company; sign-in then asks which company. A wrong password never reveals which companies an email belongs to.
- Stale browser tabs are refused. Every request says which company its page was loaded for. If the session has since moved to another company (switched in another tab), the server refuses the request (
company_changed) and the page reloads. So an old tab can never write into the wrong company. - Disabling a company signs its people out and blocks their sign-in; nothing is deleted.
Cost per request: one extra round trip to the database (set_config) inside a transaction. Indexes lead with company_id, so the security filter uses them. Background jobs (leave accrual) run one company at a time, each in its own short transaction, and never overlap.
The demo (SEED_DEMO=true) creates two companies. consultant@hrpartners.pk / Demo1234! has an account in both, to show the company picker at sign-in.
How the key rules are enforced
- One person, one record. Hiring a candidate creates the employee from the candidate's details, so nothing is typed twice. The application keeps a link to the new SIP ID.
- SIP ID is generated as
YYYY-####from a per-year counter inside the same transaction. It can't be edited and is never reused. - Payroll is computed. Each payslip is A + B − C. A is split into rate periods for mid-month joiners and increments. B lines are entered by hand and survive recomputes. C covers PF, EOBI, withholding tax, loan installments and manual deductions. Amounts are whole PKR, so the totals always add up exactly.
- Leavers are paid to their last day. Someone deactivated mid-month stays on that month's run and is paid up to the deactivation date.
- Only reviewed figures are approved. If salary, leave or loans changed after a draft run was computed, approval is refused until the run is recomputed and reviewed again.
- Leave is a ledger. Every grant, deduction, reversal and adjustment is a dated row with a running balance. Approved unpaid days reduce section A of that month's payslip.
- Nothing is hard-deleted. Employees are deactivated, and candidates and documents are soft-deleted.
- Every change is audited. Who made it, when, and the before and after values, shown under Admin → Audit trail.
- Access is checked on the server. The UI hides what a role can't use, but every API route checks the permission itself. CNIC, bank details and date of birth are only sent to roles with
employees.sensitive, or to the employee themself.
Defaults to confirm before real use
These come from the design's open questions. Each one is a setting, not hard-coded:
| Question | Default | Where to change it |
|---|---|---|
| PF rate | 8.33% of basic | Payroll → Payroll rules |
| EOBI employee share | PKR 370 / month | Payroll → Payroll rules |
| Withholding tax | Finance Act 2025 salaried slabs | Payroll → Payroll rules |
| Proration basis | Calendar days | Payroll → Payroll rules |
| Leave entitlements | Casual 10, Sick 8, Vacation 14 (7 carry forward), Unpaid | Leave → Leave types |
| Weekend and holidays | Saturday and Sunday off, no holidays | Leave → Leave types |
| SIP ID format | YYYY-#### |
server/src/services/employees.ts |