HR Portal — Technical Architecture & Data-Flow Spec

01 / FOUNDATIONS

Five architectural decisions

Everything downstream follows from these. Two are shaped by your constraints — the HRIQ API cost and PDPA — and the rest enforce the human-accountability model from the requirements spec.

Sync, don't call

The Portal reads from its own database, kept current by scheduled batch extraction from HRIQ. The expensive live API is avoided except for rare, high-value writes.

Python-first

Backend in Python to reuse your existing extraction scripts and team familiarity. Your scripts become the ingestion backbone, not throwaway tooling.

AI is sandboxed

A model never sees raw personal data it doesn't need, and never performs statutory or financial math. A gateway scrubs every prompt that crosses the trust boundary.

Deterministic core

Payroll, levy, CPF, encashment and compensation run as tested Python code with traceable breakdowns — never an LLM.

SG-resident & sealed

Personal data is hosted in-region, the Portal is not publicly routable, and every action is written to an immutable audit log.

02 / DATA SOURCING

The HRIQ sync pattern

Your existing Python-to-Excel extraction is productionised into a scheduled pipeline. Extracted files land in a secure zone, are validated against a schema, then loaded into the Portal's operational store. The Portal queries that store — fast, and free of per-call API charges.

Figure 1 · Inbound data flow — scheduled batch ingestion

HRIQ

HRIS of record

scheduled
Python extract→

Extractor

your scripts, productionised & scheduled

Excel / CSV→

Landing zone

encrypted, access-locked

validate +
transform→

Portal DB

PostgreSQL — synced copy

query→

Portal app

dashboards, AI services

Cadence & freshness

Scheduled runs — e.g. nightly full sync plus intra-day deltas for time-sensitive data (permits, attendance, OT). Tunable per dataset.
Validation gate — each import is checked for schema, row counts and anomalies before it replaces live data; a failed import is quarantined, not loaded.
Staleness indicator — every dashboard shows "data as of <timestamp>" so HR never acts on stale figures unknowingly.

Write-back (when a change must return to HRIQ)

Default: the Portal generates a formatted import file (the same format HRIQ already accepts) for a human to upload — no API cost, human-gated.
Selective API: reserve paid API writes only for low-volume, high-value cases where file import is impractical. Metered and logged.

⚠ PDPA consequenceBecause the Portal keeps a synced copy of personal data, that database is squarely in PDPA scope. It must carry the same retention, access-control and breach obligations as HRIQ itself — see §6.

03 / SYSTEM

Layered architecture

A conventional, boring-on-purpose layered design. Boring is correct for a compliance system — every layer is independently testable and the trust boundaries are explicit.

Figure 2 · Logical layers

Presentation — HR-only, behind SSO

          Role dashboards web
          Approval & case UI
          Document review
          Knowledge assistant chat
        
Application / API — auth, RBAC, orchestration

          API gateway FastAPI
          RBAC + session incl. coverage mode
          Workflow / approvals engine
          Notification service email/Teams
          Audit logger
        
Domain services

          Compliance monitor
          Calculation engine deterministic
          Report builder
          Document generator
        
AI layer — via the sandbox gateway only (§5)

          AI gateway scrub+log
          Drafting
          Retrieval / RAG
          Classification / triage
        
Data & integration

          PostgreSQL operational
          Object store documents/scans
          Vector store regs/SOPs only
          Ingestion / extractor
          Audit log append-only
        

04 / STACK

Recommended technology

Chosen for PDPA fit, your Python capability, and longevity over novelty. All mainstream and hireable — important for the maintenance-ownership concern.

Layer	Recommendation	Why
Frontend	React + TypeScript (Next.js)	Mature, component-driven, accessible; easy to find developers.
Backend	Python + FastAPI	Reuses your existing extraction scripts & team skills; fast, typed, well-documented.
Database	PostgreSQL	Relational integrity for payroll/audit; row-level security supports RBAC; strong encryption & backup tooling.
Background jobs	Celery or APScheduler + Redis	Runs scheduled extraction, monitoring scans, report generation.
Object storage	Encrypted blob store (scanned passports, medical records, letters)	Keeps large/sensitive files out of the relational DB; per-object access control.
Calculation engine	Pure Python module, 100% unit-tested	Deterministic statutory/financial math, isolated from AI and from the web layer.
Auth / SSO	OIDC / SAML (e.g. Microsoft Entra ID) + MFA	Likely already your corporate identity; restrict to the HR security group.
AI gateway	Internal service wrapping the model API	Single chokepoint for PII scrubbing, logging, purpose checks (§5).
LLM	Region-hosted, no-training endpoint (e.g. Azure OpenAI SG) or self-hosted open model for sensitive flows	Keeps inference in-region under a data-processing agreement; never a consumer endpoint.

✓ RecommendationIf you are a Microsoft/Office shop (Windows + likely M365), the path of least resistance is Entra ID for SSO and Azure (Singapore region) for hosting + Azure OpenAI — identity, residency and the AI endpoint all in one governed tenancy. AWS ap-southeast-1 or GCP asia-southeast1 are equally valid if you prefer.

05 / THE SANDBOX

How AI is walled off from personal data

This is the part that protects you. The rule: the model only ever receives the minimum it needs, de-identified, through one auditable gateway — and it is never trusted with a calculation or a final decision.

Figure 3 · The AI–PII trust boundary

🔒 Trust zone — holds PII (in-region)

Portal DB & object storeNames, FINs, passports, salaries, medical data.

Calculation engineAll payroll/levy/CPF math. Never calls the model.

Template mergeReal names/figures inserted into letters here, after AI returns.

AI Gateway

De-identify / tokenise PII
Minimise to needed fields
Purpose & role check
Log prompt + response
Route to approved model

⚠ Untrusted — the model

Receives only redacted texte.g. "Dear [EMPLOYEE_1], your bond of [AMOUNT_1]…" — placeholders, not real data.

Returns a draft / classificationReviewed by a human; re-hydrated with real values inside the trust zone.

No retention, no trainingContractual + region-locked endpoint.

The seven controls

1 · Capability boundary. The model is used only for drafting, retrieval Q&A, summarisation, classification and triage. It is structurally unable to write to the DB or trigger an action.
2 · Data minimisation. Each AI call passes only the fields that task needs — never a whole employee record.
3 · De-identification / tokenisation. Names, FINs, passport and salary values are swapped for placeholders before crossing the boundary, and re-hydrated locally afterward. The model works on a skeleton.
4 · Single gateway. Every AI call routes through one internal service that enforces 1–3, checks the caller's role and purpose, and logs the (redacted) prompt and response.
5 · Region-locked, no-train model. Inference runs on an in-region endpoint under a data-processing agreement with no training/retention — never a consumer AI product.
6 · RAG isolation. The knowledge base holds only regulations, circulars and SOPs (non-personal). Personal data is not embedded into the vector store.
7 · Human review gate. Output is labelled AI-generated and reviewed by the responsible person before anything is issued, filed or actioned.

⚠ Residual risk to acceptEven sandboxed, AI drafts can be wrong or subtly off. The human review gate (control 7) is the real backstop — it is a process control, not just a technical one, and must be enforced in the UI (nothing leaves the Portal without a named approval).

06 / SECURITY

Security & PDPA architecture

Control	Implementation
Access	SSO restricted to the HR security group; MFA enforced; Portal not publicly routable (corporate network / zero-trust access only).
Authorisation	App-level RBAC for the six roles + PostgreSQL row-level security so a query cannot return out-of-scope rows even if app logic fails.
Coverage mode	Temporary delegated access implementing the cross-training matrix (Payroll↔FW, FW→Staff, Staff→Payroll): Manager-approved, time-bounded, auto-expiring, and every action taken under delegation is flagged as such in the audit log.
Notifications	Time-critical alerts pushed to email/Teams; message content carries no sensitive personal data — it deep-links into the portal where RBAC applies. Unacknowledged critical alerts escalate up the reporting line.
Encryption	TLS 1.2+ in transit; AES-256 at rest for DB, object store and backups.
Secrets	Managed secrets vault (DB creds, model keys, HRIQ creds); no secrets in code or config files.
Audit	Append-only, tamper-evident log of every data change, AI call and human approval — user, timestamp, before/after.
Retention	Automated enforcement of the Employment Act retention clock with scheduled purge + pre-purge review.
Breach	Anomaly alerts (unusual access/export) + a documented PDPC-aligned breach-response workflow.
Residency	All personal data stored and processed in Singapore region, including the AI endpoint.
Assurance	Independent security review + penetration test before any phase that handles personal or financial data goes live.

6B / CV INTAKE

CV parsing — upload to structured record

CVs are the single input to recruitment; AI does the data entry. Whether a candidate uploads through the public application page or HR uploads an agency/walk-in CV, the file follows one pipeline: stored encrypted, parsed by AI into structured fields, written to the database, and scored for fit — no manual keying.

Figure 4 · CV intake & parsing pipeline

CV upload

application page or HR upload

file +
consent→

Object store

encrypted · virus-scanned

document text→

AI parser

OCR + entity extraction, via gateway

structured
fields→

Candidate record

PostgreSQL (structured)

skills →
fit score→

Screening pipeline

ranked shortlist

A CV is uploaded — by a candidate on the public application page (consent captured at source) or by HR for an agency / walk-in / referral CV (consent + source recorded).

File lands in the encrypted object store and is virus-scanned. The raw CV is personal data — it carries the retention clock from day one.

AI parser extracts name, contact, experience, role and skills (OCR for scans + entity extraction). Only the minimal document text needed crosses the AI gateway; the structured result returns to the trust zone.

Fields are written as a structured candidate record in PostgreSQL, linked to the stored file. Low-confidence fields are flagged.

Fit score is computed deterministically — extracted skills/experience matched against the role profile — and the candidate enters the screening pipeline, ranked.

Human reviews the extracted fields and the ranking before routing to a hirer. Extraction is assisted, not autonomous.

⚠ Two design constraintsAccuracy: CV layouts are messy; parsing is never 100%. The review-and-correct step stays, and low-confidence fields are flagged rather than trusted. Explainable ranking: the fit score is deterministic skill/experience matching — not an opaque LLM judgement — so a shortlisting decision can always be explained and defended (relevant to FCF / anti-discrimination record-keeping).

6C / EXTERNAL ACTORS

Non-HR actors & how they touch the system

The portal is HR-only, but the job scopes involve several non-HR actors. None of them get portal accounts — each gets a purpose-built channel. The secure one-time link pattern (single-purpose, expiring, no login, minimal data) serves every "respond to one question" case.

Actor	Interaction	Channel
Hiring managers	Review shortlisted CV, register interest	One-time link (outbound email → response recorded in Recruitment)
Site supervisors	Confirm missing/abnormal OT entries; leave-coverage coordination	One-time link or email digest from the Assistant's chase queue
Candidates	Apply, upload CV, receive invites & offers	Public application page (§6B) + outbound email
EHS department	Incident reports in (trigger claim cases); weekly OT exception report out (fatigue monitoring)	Structured intake (form/file drop) inbound; scheduled report delivery outbound
Finance	Wage-subsidy/grant reconciliation; grading flags	File exchange / shared reports (INT-04)
Operations	Site-deployment data for tender cross-checks & headcount reconciliation	Batch file exchange (INT-04)
Head of HR / Director	Approvals above Manager DOA tier; HR Assurance Summary	Head of HR is a portal user; Director receives escalations via the Head of HR

07 / WALKTHROUGHS

Two end-to-end flows

A · Generating a bond letter (AI-assisted)

Executive (Staff) selects an employee and "draft bond letter" in their workspace.

App fetches needed fields from the Portal DB (trust zone) — bond terms, dates.

AI Gateway de-identifies: real name/amount become [EMPLOYEE_1], [AMOUNT_1]; only the skeleton crosses to the model.

Model returns drafted letter prose with placeholders intact; gateway logs the exchange.

Template merge inside the trust zone re-inserts real values. Draft labelled "AI-generated".

Human review gate: Executive (and approver per DOA) reviews and releases. Issued version archived; action audited.

B · DRC / permit-expiry alert (AI-led monitoring)

Nightly extraction refreshes worker/permit data into the Portal DB.

Compliance monitor (deterministic) recomputes DRC headroom and scans permit/passport expiry windows.

Threshold breaches and upcoming expiries become prioritised alerts with owner + due date.

FW Executive sees them on the compliance board at login; the monthly DRC report is auto-compiled for the HR Manager.

Human acts: the Executive initiates renewal/correction; the Manager approves corrective action. No money or filing moves without a person.

Note flow B touches no LLM at all — the highest-value monitoring is pure deterministic code. AI is the assistant, not the engine.

08 / OPS & OPEN ITEMS

Environments & decisions still open

Environments & operations

Three environments — Dev, Staging (with synthetic/masked data), Production. No real PII in Dev.
Backups — automated daily, encrypted, with periodically tested restores.
Monitoring — uptime, job-failure alerts (a failed extraction must page someone), and audit-log review.
Parallel-run — payroll/calculation outputs reconciled against the current process before becoming authoritative (per the SRS phasing).

Decisions that need your input

Decision	Options / note
Cloud vs on-prem	Cloud SG-region (recommended, faster/cheaper) vs on-prem if company policy forbids cloud for HR data.
Identity provider	Confirm Entra ID / Google Workspace / other — drives SSO & possibly hosting.
Self-hosted vs API model	API model (simpler, region-locked) vs self-hosted open model (max data control, more ops). Can mix per sensitivity.
Extraction cadence	How fresh must each dataset be? Drives schedule and intra-day delta design.
Existing scripts	Share current Python extraction scripts so they can be assessed and folded into the ingestion layer.