People Platform: how we build it

01What the workbook changed

The schema workbook was read end to end — 95 columns, 10 tabs, all 32 people. It is an unusually good document, and working through it closed three of its own blocking flags and opened one question nobody had asked.

The one question the workbook does not ask: every salary figure in the company is SGD, and no local-currency figure exists in any source. All five Singapore staff are paid by bank transfer; all twenty-seven others through Wise into a local account. That is the signature of an SGD contract settled abroad, not of local-currency pay.

If that is right — and we have taken it as right — then salaries are contracted in SGD, and the flag asking us to collect twenty-seven local salary figures before payroll can start is asking for something that does not exist. It changes the shape of the compensation table and it removes a blocker.

02One system, four parts

The platform is one application and one database. Inside it, the work is split into four parts, and the split is not cosmetic — it is a rule about who is allowed to depend on whom.

%%{init: {"flowchart": {"padding": 16, "nodeSpacing": 58, "rankSpacing": 62, "useMaxWidth": true}}}%%
flowchart TB
  HRMS["HRMS
payroll, claims, budget
used by 2 people daily"]
  ORG["ORG CHART
reporting tree, directory
used by all 32"]
  LEAVE["LEAVE
balances, requests, awards
used by all 32"]
  CORE["CORE
the one record of each person — name, contact,
reporting line, pay, login, permissions
built once, never rebuilt"]

  HRMS  -->|"reads people from"| CORE
  ORG   -->|"reads people from"| CORE
  LEAVE -->|"reads people from"| CORE
  LEAVE -.->|"unpaid leave only"| HRMS

Three consequences follow from that picture, and they are the reason it is worth drawing:

• A person is entered once. A new starter is created in Core. They appear in the org chart, in the leave system and on the payroll immediately, because all three are reading the same row rather than keeping their own copy. Nobody is ever "added to the leave system".
• A new module is added, not merged in. When we build Leave, we do not open up payroll to do it. Leave gets its own tables and reads Core. Payroll keeps running throughout.
• Core has to be right first. It is the only part every other part depends on, so it is phase one, and it is designed for all four modules now rather than grown one module at a time. That is the single biggest reason the build order is what it is.

The dotted arrow is the one place this rule bends. Unpaid leave reduces someone's pay, so Leave has to tell payroll about it. We are building that as a one-directional handover — Leave reports days, payroll decides money — rather than letting the two modules read each other freely.

03The data model

The workbook describes one employee record with 95 columns. We are splitting it into tables. The main reason is access: “only Finance may see this” becomes one rule on one table, rather than a column-by-column rule that every screen has to remember and any screen can forget.

The person

One employee record, with the sensitive parts lifted out into their own tables. The two links to account and company_card are “none or one” on purpose: not everyone has a login, and not everyone holds a card.

%%{init: {"er": {"entityPadding": 18, "minEntityWidth": 170, "diagramPadding": 22, "fontSize": 13}}}%%
erDiagram
  CAREER_FRAMEWORK ||--o{ EMPLOYEE : "gives the job title to"
  EMPLOYEE ||--o{ EMPLOYEE : "supervises"
  EMPLOYEE ||--o| EMPLOYEE_PERSONAL : "has one"
  EMPLOYEE ||--o| EMPLOYEE_COMPENSATION : "has one"
  EMPLOYEE ||--o| COMPANY_CARD : "may hold"

  EMPLOYEE {
    uuid id PK
    text employee_code UK
    text full_name
    text work_email UK
    text phone_number "new"
    text country_of_work
    text office
    text department
    int career_scale "1 to 9"
    text career_track
    uuid framework_id FK
    uuid supervisor_id FK "an employee"
    date hire_date
    date probation_end_date
    date last_working_day
    text engagement_type
    text working_hours
  }
  EMPLOYEE_PERSONAL {
    uuid employee_id PK
    text personal_email "new"
    date date_of_birth
    text nationality
    text marital_status
    text home_address
    text emergency_name
    text emergency_phone
    text id_document_type
    date passport_expiry
  }
  EMPLOYEE_COMPENSATION {
    uuid employee_id PK
    numeric monthly_salary_sgd
    text statutory_scheme
    text cpf_residency
    bytea national_id "encrypted"
    bytea passport_number "encrypted"
    bytea bank_account_no "encrypted"
    text bank_name
    text payment_rail
  }
  CAREER_FRAMEWORK {
    uuid id PK
    int scale "1 to 9"
    text track
    text seniority_label
    int months_to_promotion
    date version_from
  }
  COMPANY_CARD {
    uuid id PK
    uuid employee_id FK
    numeric monthly_limit_sgd
    bool is_unlimited
    date issued_on
  }

Note what is not stored on the employee: job title, seniority label, and when they are next up for promotion. All three are read from the career framework using the scale and track. That is why the framework arrow points at the employee and not away from it — and it is why Andre's and Neesha's mis-typed titles in the workbook become impossible rather than merely corrected.

Access

Being able to log in and being employed are two different facts, so they are two different tables. Someone who has left can keep read access through a handover; someone who has joined but not been set up yet exists in the directory with no account at all.

%%{init: {"er": {"entityPadding": 18, "minEntityWidth": 170, "diagramPadding": 22, "fontSize": 13}}}%%
erDiagram
  EMPLOYEE ||--o| ACCOUNT : "may log in through"
  ACCOUNT ||--o{ ROLE_ASSIGNMENT : "is granted"
  ROLE ||--o{ ROLE_ASSIGNMENT : "appears in"
  ROLE ||--o{ ROLE_PERMISSION : "bundles"
  PERMISSION ||--o{ ROLE_PERMISSION : "appears in"
  EMPLOYEE ||--o{ APPROVER_OVERRIDE : "may be redirected by"
  ACCOUNT ||--o{ AUDIT_LOG : "leaves a trail in"

  EMPLOYEE {
    uuid id PK
    text full_name
  }
  ACCOUNT {
    uuid id PK
    uuid employee_id FK
    text status
    timestamptz last_sign_in_at
  }
  ROLE {
    text code PK
    text display_name
  }
  PERMISSION {
    text code PK
    text module
  }
  ROLE_ASSIGNMENT {
    uuid account_id FK
    text role_code FK
    date granted_on
  }
  ROLE_PERMISSION {
    text role_code FK
    text permission_code FK
  }
  APPROVER_OVERRIDE {
    uuid id PK
    uuid employee_id FK
    text request_kind
    uuid approver_id FK
    text reason
  }
  AUDIT_LOG {
    uuid id PK
    uuid account_id FK
    text action
    text target
    timestamptz occurred_at
  }

Claims

Four tables. The one to look at is claim_approval — approvals are rows, not a column on the claim, which is what lets the system hold two signatures and check they came from two different people.

%%{init: {"er": {"entityPadding": 18, "minEntityWidth": 175, "diagramPadding": 22, "fontSize": 13}}}%%
erDiagram
  EMPLOYEE ||--o{ CLAIM : "submits"
  CLAIM_CATEGORY ||--o{ CLAIM : "sets the tax treatment of"
  CLAIM ||--|{ CLAIM_APPROVAL : "collects two of"
  EMPLOYEE ||--o{ CLAIM_APPROVAL : "signs"

  EMPLOYEE {
    uuid id PK
    text full_name
  }
  CLAIM_CATEGORY {
    uuid id PK
    text name
    text tax_treatment
    numeric default_cap_sgd
  }
  CLAIM {
    uuid id PK
    uuid employee_id FK
    uuid category_id FK
    numeric amount
    text currency
    text receipt_url
    text state
  }
  CLAIM_APPROVAL {
    uuid id PK
    uuid claim_id FK
    text stage
    uuid approver_id FK
    timestamptz decided_at
  }

Payroll

The run is the spine: one payroll_run per month, holding one payroll_line per person. Everything to the left of the line feeds into it; the settlement to the right records what happened afterwards.

%%{init: {"er": {"entityPadding": 18, "minEntityWidth": 175, "diagramPadding": 22, "fontSize": 13}}}%%
erDiagram
  PAYROLL_RUN ||--|{ PAYROLL_LINE : "holds one per person"
  EMPLOYEE ||--o{ PAYROLL_LINE : "is paid through"
  SALARY_HISTORY ||--o{ PAYROLL_LINE : "sets base pay for"
  STATUTORY_RATE ||--o{ PAYROLL_LINE : "converts to local for"
  STATUTORY_CONFIG ||--o{ PAYROLL_LINE : "computes contributions for"
  CLAIM ||--o| PAYROLL_LINE : "is settled in"
  PAYROLL_LINE ||--o| SETTLEMENT : "results in"
  EMPLOYEE ||--o{ SALARY_HISTORY : "has a dated series of"

  SALARY_HISTORY {
    uuid id PK
    uuid employee_id FK
    numeric monthly_salary_sgd
    date effective_from
  }
  STATUTORY_RATE {
    uuid id PK
    text country_code
    text payroll_month
    numeric sgd_to_local
  }
  STATUTORY_CONFIG {
    uuid id PK
    text country_code
    text scheme
    jsonb bands
    date effective_from
  }
  PAYROLL_RUN {
    uuid id PK
    text payroll_month
    text state
    uuid finalised_by FK
  }
  PAYROLL_LINE {
    uuid id PK
    uuid run_id FK
    uuid employee_id FK
    numeric base_pay_sgd
    numeric claims_sgd
    numeric unpaid_leave_days
    numeric employee_contributions
    numeric employer_contributions
    numeric net_pay_local
    numeric total_staff_cost_sgd
  }
  SETTLEMENT {
    uuid id PK
    uuid payroll_line_id FK
    numeric amount_local
    numeric settlement_rate
    text rail
    date paid_on
  }

Leave

Built in phase one, used in phase four. The important thing about this diagram is what it does not contain: there is no balance column anywhere.

%%{init: {"er": {"entityPadding": 18, "minEntityWidth": 175, "diagramPadding": 22, "fontSize": 13}}}%%
erDiagram
  LEAVE_POLICY ||--o{ LEAVE_ENTITLEMENT : "sets base days for"
  EMPLOYEE ||--o{ LEAVE_ENTITLEMENT : "has one per leave year"
  EMPLOYEE ||--o{ AWARD_LEDGER : "is granted extra days in"
  EMPLOYEE ||--o{ LEAVE_REQUEST : "books"
  LEAVE_TYPE ||--o{ LEAVE_REQUEST : "classifies"
  LEAVE_TYPE ||--o{ AWARD_LEDGER : "classifies"
  HOLIDAY_CALENDAR ||--o{ AWARD_LEDGER : "justifies the gap award in"

  LEAVE_POLICY {
    uuid id PK
    int base_annual_days
    text pro_rate_rule
    int carry_forward_cap_days
    date carry_forward_expires
    int sick_days_cap
    int hospitalisation_cap
  }
  LEAVE_TYPE {
    text code PK
    text name
    bool draws_down_allowance
    bool is_unpaid
  }
  HOLIDAY_CALENDAR {
    uuid id PK
    text country_code
    date holiday_date
    text name
  }
  LEAVE_ENTITLEMENT {
    uuid id PK
    uuid employee_id FK
    int leave_year
    numeric base_days
    numeric prorated_days
    numeric carry_forward_in
    date carry_forward_expiry
  }
  AWARD_LEDGER {
    uuid id PK
    uuid employee_id FK
    text award_kind
    numeric days
    date awarded_on
    date expires_on
    uuid granted_by FK
    text reason
  }
  LEAVE_REQUEST {
    uuid id PK
    uuid employee_id FK
    text type_code FK
    date start_date
    date end_date
    numeric days
    text state
    uuid approver_id FK
  }

The tables, and who can read them

04How the three main flows work

These are the three places where the system decides something rather than merely records it, so they are the three worth checking most carefully.

Claims

%%{init: {"flowchart": {"padding": 16, "nodeSpacing": 55, "rankSpacing": 52, "useMaxWidth": true}}}%%
flowchart TB
  A["Employee submits
in the receipt currency"] --> B{"Within
benefit cap?"}
  B -- no --> X["Rejected on the spot"]
  B -- yes --> C["Finance approves
Arul or Agus"]
  C --> D["Super Admin approves
Yashwin or Anwar"]
  D --> E["Pulled into the
payroll month"]
  E --> F{"Category
treatment"}
  F -- reimbursement --> G["Paid on top of net
no tax, no contributions"]
  F -- "taxable allowance" --> H["Added to gross
before contributions"]

The consequence worth stating out loud: the approver pool is four people. Two at each stage, and self-approval is blocked, so a claim submitted by one of the four leaves exactly one person able to sign it. One absence stalls a stage. That is the price of the control, and it is the reason the pool should grow before the company does.

Payroll

%%{init: {"flowchart": {"padding": 16, "nodeSpacing": 55, "rankSpacing": 52, "useMaxWidth": true}}}%%
flowchart TB
  R["Finance sets the month's
SGD to local rate per country"] --> S["Generate the run"]
  S --> T["For each person: salary in SGD
+ approved claims
- unpaid leave"]
  T --> U["Convert to local at the
month's declared rate"]
  U --> V["Compute contributions
CPF · EPF/SOCSO · BPJS · none"]
  V --> W["Finance submits"]
  W --> Y["Super Admin finalises"]
  Y --> Z["Money sent"]
  Z --> AA["Record what the rail
actually charged"]
  M["A missing rate stops the run
and names what is missing"] -.-> S

Leave

%%{init: {"flowchart": {"padding": 16, "nodeSpacing": 55, "rankSpacing": 52, "useMaxWidth": true}}}%%
flowchart TB
  P["Employee requests leave"] --> Q{"Does this type draw
down the allowance?"}
  Q -- "no — sick, birthday,
parental, unpaid" --> R2["Recorded, allowance untouched"]
  Q -- "yes — annual, half days" --> S2["Their manager approves"]
  S2 --> T2["Balance recalculated in order"]
  T2 --> U2["1 — carry forward
expires 31 March"]
  U2 --> V2["2 — off-in-lieu"]
  V2 --> W2["3 — base + service award"]
  R2 --> X2{"Unpaid?"}
  X2 -- yes --> Y2["Deduction handed to payroll"]

05What each person can do

Four levels of access. Everyone has the first; thirteen people also have the second; two people have the third; two people have the fourth. This section is the one worth reading closely, because it is the part that is hardest to change later without someone noticing.

%%{init: {"flowchart": {"padding": 16, "nodeSpacing": 40, "rankSpacing": 70, "useMaxWidth": true}}}%%
flowchart LR
  L["Sign in"] --> H["Home"]
  H --> D["Directory and org chart
everyone's contact card"]
  H --> M["My record
view it; ask HR to change it"]
  H --> C["Claims
submit, track, see the cap left"]
  H --> V["My leave
balance, request, history"]

%%{init: {"flowchart": {"padding": 16, "nodeSpacing": 40, "rankSpacing": 70, "useMaxWidth": true}}}%%
flowchart LR
  E["Everything an employee
can do"] --> A["Approvals inbox"]
  A --> B{"Team member's
leave request"}
  B -- approve --> C["Balance updates
team calendar updates"]
  B -- reject --> D["Returned with a reason"]
  E --> F["My team
who is out, balances,
probation dates"]
  E --> G["Grant off-in-lieu
for a holiday or
weekend worked"]

%%{init: {"flowchart": {"padding": 16, "nodeSpacing": 45, "rankSpacing": 55, "useMaxWidth": true}}}%%
flowchart TB
  A["Sign in — Arul or Agus"] --> B["People admin
new starter, leaver, promotion,
reporting line, personal details"]
  A --> C["Pay and bank details
opened daily; every open logged"]
  A --> H["Claims queue
first approval"]
  A --> D["Set the month's
declared exchange rates"]
  D --> E["Generate the payroll run"]
  E --> F["Review every line"]
  F --> G["Submit for finalisation"]
  G -.-> I["Waits for a Super Admin"]
  H -.-> I
  I --> J["Record each settlement
after the transfer clears"]

%%{init: {"flowchart": {"padding": 16, "nodeSpacing": 45, "rankSpacing": 55, "useMaxWidth": true}}}%%
flowchart TB
  A["Sign in — Yashwin or Anwar"] --> B["Finalise the payroll run
no money moves before this"]
  A --> C["Final approval on every claim"]
  A --> D["Change what the system means
career framework · leave policy · benefit caps"]
  A --> E["Grant and revoke access"]
  A --> F["Read the audit log"]
  A --> G["Pay and bank details
full access, same as Finance"]

The same thing, as a table

06What each feature reads and writes

The same picture from the other side — every screen we build, and exactly which tables it touches. This is the checklist we build against.

07The build, in order

Four phases, in dependency order. No dates — several items depend on decisions and data that are not ours to schedule. The ordering itself is what we are asking you to approve.

08Decisions we need from you

Seven items only you can settle. They are ordered by how much they hold up: the first three change what we build, the last four are corrections to the data we are about to import.

1. 01

   The parental leave code must be renamed before we take the final export hard deadline

   Parental leave and afternoon half-day annual leave currently share the code PM. One draws down the annual allowance and one does not. If we migrate as-is, some parental leave silently becomes annual leave and quietly eats people's balances — and it will not be obvious until someone runs out of days they thought they had.

   What we need: HR to rename parental leave to PML in the tracker before we take the export. This is the only item on this page with a deadline attached, and it is the only one that silently corrupts data if it slips.

2. 02

   Does off-in-lieu expire? shapes the leave tables

   Today it never does. Natalie holds 11.5 days and Miguel 8, and the balance grows every January when the holiday-gap award is posted. Nothing in the tracker removes it, so it is an obligation that only ever increases — and on the day someone leaves, it is payable.

   What we need: either an expiry window — twelve months is usual — or a decision to accept it as a permanent liability, in which case Finance should be booking it. This is field award_ledger.expires_on in Figure 6; we can build either, but not neither.

3. 03

   Sick and hospitalisation limits outside Singapore

   All 32 people are currently set to Singapore's statutory 14 and 60 days, including the 22 in Jakarta. Indonesia and Malaysia differ, and Malaysia's varies with length of service. The tracker applies no cap at all, so nobody has ever hit one.

   What we need: the correct figures for Indonesia and Malaysia, and a decision on whether sick leave is capped in practice at all. If the honest answer is "we do not cap it", that is a valid answer and simpler to build.

4. 04

   How is the leave accrual change communicated?

   Service leave now accrues on 1 January instead of on each person's work anniversary. We are grandfathering 2026 so nobody loses a day mid-year, and the new rule takes effect on 1 January 2027. Thirteen people will have one day fewer than the old rule would have given them.

   What we need: agreement that this is communicated before January, and by whom. Taking a day back without notice is the kind of thing people notice.

5. 05

   Identity document types need re-collecting

   Every one of the 32 records says the identity document is a passport. That is only true for Miguel, who has no Philippine equivalent to a national ID card. Payroll cannot validate an Indonesian KTP or a Singapore NRIC if all of them are labelled passport.

   What we need: HR to re-collect the document type for the other 31. The numbers themselves are already on file and do not need re-collecting.

6. 06

   Arul's carry-forward is 6 days against a cap of 5

   Everybody else is at or below the cap.

   What we need: confirm it as an agreed exception, or correct it before we import. Whichever you choose, the system will hold the cap afterwards.

7. 07

   Novicto's card limit is 50 at a scale where everyone else is 25

   Card limits otherwise follow career scale exactly. Lisa's is still at her old scale's limit seven weeks after her June promotion, which is what happens when a figure is typed rather than derived — we are fixing that by deriving it.

   What we need: is Novicto's 50 deliberate, or was it never corrected? A deliberate exception is fine; we will record it as one rather than let it look like a mistake.

Answered, and needing nothing further from you

• Salary importFinance or a Super Admin loads the salary figures directly into the live system. Nobody else, and no copy of the figures leaves that boundary at any point.
• HolidaysThe whole company works the Singapore calendar, wherever they sit, and staff elsewhere are compensated with off-in-lieu for the gap. We build one calendar, not six.
• Work emailWork addresses are @kpimedia.sg and are treated as unique — one address, one person, used as the sign-in identity.
• Personal emailAdded as a field in phase one. HR collects it where missing; it is what keeps someone reachable after their work account is closed.
• PassportsFour have already expired. We build the expiry alert in phase three; chasing them is an HR matter and does not block the build.
• PhotosNot imported. The current Google Drive links break whenever permissions change, so each person uploads their own after launch and the image is stored in the platform.

09Questions we have not asked yet

Section 08 is about what we build. This section is about everything around it — cutting over, running it, and what happens to the people using it. None of these block starting. All of them block launching, and they are much cheaper to answer now than in the week before go-live.

They are grouped by who we think should answer, but that is a suggestion rather than an assignment. Several have a sensible default and we have said what it is — for those, silence is a workable answer and we will proceed on the default.

10Already decided

Twenty-one decisions taken so far, each recorded in full alongside the code with its reasoning and what it costs us. Listed here so nothing is a surprise later — and so you can reverse any of them now, while reversing them is cheap.