DocsGet started

Core concepts

The five objects that carry almost everything in HRTEQ, why the deployment lifecycle lives on the application rather than the person, and how tenant isolation is enforced.

5 min readLast updated September 3, 2026

HRTEQ has fifty-odd tables, but you only need five nouns to read the rest of these docs. Getting them straight — particularly the difference between an applicant and an application — saves a lot of confusion later.

The five objects#

Applicant: A person. Created once, kept forever, and identified by an applicantNo such as APP-2026-000001. Holds identity documents that belong to the person rather than to a job: passport, NBI clearance, PSA birth certificate, TESDA certificates.
Principal: The overseas employer company, with an accreditation number and its own expiry. Its people are PrincipalContact records, and a contact can be given portal access.
Job order: Demand from a principal, coded like JO-2026-0001. Carries the jobsite country and city, contract duration, salary, benefits, validity date, and whether it is published to your job board.
Position: A role within a job order, with a quota. Ten welders and two foremen on one job order are two positions.
Application: One applicant against one position. This is the object that moves. It holds the stage, the per-deployment documents, the checklist, the charges, and every timestamp from endorsement to departure.

Why the lifecycle lives on the application#

It is tempting to put a status on the person. HRTEQ deliberately does not, because one person can be in flight for two jobs at once and the two situations are genuinely independent.

Maria can be at MEDICAL for a Riyadh housekeeping position and still sitting at SCREENING for a Tokyo caregiving position. Each has its own stage, its own contract, its own medical result and its own balance. A single status on Maria could not express that, and forcing one would mean losing a record every time an applicant is endorsed twice.

The applicant does carry a coarse ApplicantStatus — LEAD, ACTIVE, DEPLOYED, INACTIVE, BLACKLISTED — but it exists for list filtering and reporting, not for the workflow. Reaching the DEPLOYED stage on any application flips the applicant to DEPLOYED so lists and reports agree with the board.

Documents belong to one or the other#

Every document type declares an appliesTo of APPLICANT or APPLICATION, and that decides where the file lives.

Applies to	Examples	Rationale
`APPLICANT`	Passport, PSA birth certificate, NBI clearance, TESDA NC, DMW e-Registration	The document describes the person. Uploaded once and reused across every application they are part of.
`APPLICATION`	Employment contract, medical result, visa, OEC, airline ticket	The document only makes sense against one specific deployment. A second application needs its own.

When the gate checks a document requirement it looks in both pools, so a stage requirement can reference a passport and a visa without caring which object each is attached to.

Stages and requirements#

A stage is a row in StageDefinition: a code, a name, a sort order, an owning role, and a flag for whether it is terminal. Each stage carries StageRequirement rows, and those are entry conditions — they are evaluated against the stage an application is trying to move *into*, never the one it is leaving.

The owning role is the second half of the rule. Only the role that owns the target stage — or an Owner or System Administrator — may move an application there. That is what makes a handoff between officers explicit instead of implied.

Stages are your data, not our code. The 22 seeded stages are a DMW-aligned starting point. Codes, names, order, owning roles and requirements are all editable per agency, so treat every stage name in these docs as a default rather than a constant. Stage gates covers the evaluation rules.

Selection: endorsements and interviews#

Endorsement: A submission of an application to the principal for a decision: PENDING, SHORTLISTED, INTERVIEW, REJECTED, SELECTED. The applicant’s contact details stay hidden until the decision reaches SELECTED, and the reveal is audited.
Interview plan: A scheduled session with a numbered participant queue. Running it produces an InterviewResult per participant, and a PASSED result completes the checklist item that the SELECTED stage requires.

Users, surfaces and roles#

A User has a userType — the surface they sign in on — and, for staff, a staffRole.

`userType`	Signs in at	What they see
`STAFF`	`/login`	The agency workspace. Their `staffRole` decides what they can write.
`APPLICANT`	`/portal`	Their own record. A separate guard, not the staff matrix.
`EMPLOYER`	`/employer`	A principal contact’s view. Read-only today — see Endorsements and the principal portal.
`PLATFORM`	—	HRTEQ operators. Outside any single organization.

Users are unique on the pair of email and userType, so the same address can legitimately be a staff account and an applicant account. That is why sign-in takes a surface alongside the credentials.

"Employer" is a surface; "principal" is the company. The docs and the UI use principal for the overseas employer organization and employer only for the login surface and the EMPLOYER user type. They are not interchangeable.

Tenancy and isolation#

Every tenant-owned row carries an organizationId. Isolation is not left to whoever wrote the query: a Prisma client extension inspects each query against a tenant table and throws if there is no organization filter, so an accidentally unscoped read fails loudly instead of leaking.

There is no branch or office model. Tenancy is the organization and nothing below it. There is no way to scope a recruiter, a job order or a permission to a branch. If you run multiple offices under one licence, they share one workspace.

A worked example#

A principal, Gulf Star Facilities, is accredited and on file.
They send a job order JO-2026-0007 for Riyadh with two positions: 10 × Housekeeping Attendant, 2 × Housekeeping Supervisor.
Maria Santos walks in and becomes applicant APP-2026-000001. She uploads her passport and résumé — both applicant-level documents.
A recruitment officer endorses Maria to the Housekeeping Attendant position. That creates the application, and a card appears at LEAD.
The application collects its own documents as it moves: offer letter, employment contract, medical result, visa, OEC, ticket.
Each stage entry is checked against that stage’s requirements. Each move is written to ApplicationStageHistory with who did it, and to the audit log.
Maria reaches DEPLOYED. Her applicant record flips to DEPLOYED and a Deployment row is created for post-arrival welfare monitoring.

Was this page helpful?