PROJECT PROFILE — CarePortal: Care-Staffing Broker Platform

1. Snapshot

The agency — an Australian nursing & disability-care staffing business (multi-office, multi-state) — ran its operation across a fragmented stack: separate demand portals (Beeline, used by a national hospital group via a managed-service provider; Staff Central, used by an aged-care provider), a supply system of record (Brevity), accounting tools (MYOB, QuickSuper), the NDIS PRODA portal, and paper timesheets — with coordinators manually racing to accept shifts, re-keying the same nurses into every portal, and computing award-compliant pay by hand. Agentryx designed and built CarePortal, a broker-spine platform that consolidates these into one hub and runs the full lifecycle end-to-end: ingest demand → AI-match an available, compliant nurse → dispatch/accept → clock → SCHADS award calculation → pay-period close with MYOB / QuickSuper / NDIS export → supply write-back. The complete pipeline is built and verified on staging against a purpose-built suite of vendor simulators; a real-data pilot (email ingestion + portal automation) is now being stood up.

2. The Challenge

The agency sits in the middle of a three-sided market: facilities and hospitals post demand, nurses are the supply, and the agency is the broker that fills the gap — fast, compliantly, and profitably. The operating reality made that hard. Demand arrives across multiple third-party portals, none of which expose a usable API, and each works differently: Beeline is a classic vendor-management system operated by a managed-service provider as an MSP on a submit-a-candidate model; Staff Central is an assign-your-own-employee model; both notify by email and gate login behind email one-time codes. Supply lives in Brevity (the system of record for nurses and pay), while nurse availability is held in phone calls and email, not in any app. Accounting and compliance run through MYOB, QuickSuper and the NDIS PRODA portal. Day to day, coordinators watch several inboxes, race — often inside a one-hour window — to win shifts by hand, maintain the same roster and credentials separately in every portal, and reconcile award pay manually.

The hard constraints that shaped the design: a heavy Australian regulatory load (AHPRA registration currency, NDIS, and Fair Work / SCHADS award penalty rules across eight state/territory public-holiday calendars); three incompatible vendor acceptance models with no APIs; sparse availability data; and an explicit mandate to integrate, not replace — the agency keeps the tools it already pays for, and CarePortal becomes the faster front door in front of them.

3. What We Built

CarePortal is a coordinator web console + nurse PWA + mobile app over a typed API backend, built as the hub between demand and supply. The delivered system spans:

• Demand & matching — a unified shift inbox that ingests jobs (with an email-ingestion adapter for the real portals), feeding a six-stage matching pipeline (intake → hard filters → feature extraction → scoring → confidence → explainability). A UI-configurable AI matchmaker (Anthropic Claude / Google Gemini / OpenRouter) layers on a rules engine that enforces qualification gating, the RN → EN → AIN scope hierarchy, AHPRA currency and availability.
• Dispatch & acceptance — an open-shift board with first-to-accept atomic claim, broadcast-to-top-N, and notice-tiered post-acceptance withdrawal.
• Supply write-back — a Brevity integration that creates a Service Schedule and assigns the won nurse (idempotent), surfaced as a coordinator "Push to Brevity" action on a delivered shift, plus the roster/credential model.
• Delivery & award-compliant pay — nurse clock-in/out, a full SCHADS award engine (six-bucket penalty stack + AU public-holiday calendar across eight jurisdictions), a pay-period lifecycle (open → locked → exported-to-MYOB → exported-to-QuickSuper → closed), one-click idempotent vendor exports (MYOB pay-run + invoices, QuickSuper SAFF super file, NDIS PRODA claims), and admin-configurable per-role pay rates.
• Nurse PWA + Expo mobile app — accept shifts, clock on/off, and file incident reports (aligned to NDIS / aged-care incident obligations).
• A seven-vendor simulator suite (Beeline, Staff Central, Brevity, MYOB, QuickSuper, NDIS PRODA, Twilio) so the entire loop is demonstrable on staging without real vendor credentials.
• A pilot integration layer — a mail-forwarding design plus a Gmail-API OAuth connector to ingest real demand emails (and login OTPs), a headless-browser (RPA) write path for API-less portals, and an in-portal Discovery & Verification hub (versioned, fillable, with screenshot attachments) used to run client/partner discovery collaboratively.

4. Architecture & How It Works

CarePortal is a TypeScript pnpm monorepo. The coordinator console is React + Vite (wouter routing, a shared design system) consuming an OpenAPI-specified API through an Orval-generated React-Query client; a separate nurse PWA and an Expo / React Native mobile app reuse the same typed client. The backend is an Express API (esbuild-bundled, run under systemd behind nginx + TLS) over PostgreSQL with Drizzle ORM and versioned migrations.

Two decisions define the platform. (1) Strategy interfaces, adapters and a broker_org_id tenancy axis from day one — ingestion adapters, a pluggable matchmaking engine, and an AI-provider strategy — so the same core later absorbed an AI matcher and remains ready for a multi-broker SaaS without rework ("ship narrow, architect wide"). (2) Build against vendor simulators first — a fleet of HTTP simulators models each external system, so the full ingest → match → accept → pay → write-back loop runs and is demoed on staging; the adapter seam then swaps a simulator for the real vendor with no change to the core.

Structured vendor discovery established the production integration archetype: because none of the demand portals (Beeline, Staff Central) or the supply system (Brevity) expose usable APIs, the real path is email-ingest (structured notification emails, parsed) + headless-browser automation (RPA) for the write action + file import/export, with login OTPs read from a controlled mailbox via the Gmail API over OAuth — chosen after proving that Google now blocks basic-auth IMAP (and retired its legacy unlock page) from data-centre IPs. Pay computation is config-in-DB (per-role rates, award rules) so policy changes don't need code; vendor exports are idempotent (keyed on the export artefact) so a repeat push is a safe no-op. Access is JWT + role-based (coordinator, nurse, auditor, architect-dev) with path-scoped authorization and a tamper-evident audit log.

5. Technology Stack

• Frontend: React, Vite, wouter, TailwindCSS + shared design system; nurse PWA; Expo / React Native (SDK 56) mobile.
• Backend: Node.js, TypeScript, Express, esbuild bundling, background jobs; OpenAPI 3 contract → Orval-generated typed client + Zod schemas.
• Data: PostgreSQL, Drizzle ORM, SQL migrations, JSONB config, atomic first-to-accept claim logic, audit log.
• AI/ML: UI-configurable LLM matchmaker via Anthropic Claude / Google Gemini / OpenRouter (provider-pluggable); hybrid rules-plus-AI scoring with explainability.
• Integrations: vendor write-back (Brevity), MYOB pay-run/invoice, QuickSuper SAFF, NDIS PRODA claims, Twilio SMS; Gmail API (OAuth) email-ingest; Playwright headless-browser RPA for API-less portals; Microsoft 365 mail-forwarding.
• Infra & deployment: GCP VM, nginx + Let's Encrypt TLS, systemd services, a seven-vendor HTTP simulator fleet + orchestrator, versioned web/API deploys.
• Security & compliance: JWT auth, RBAC, audit logging, AHPRA / NDIS / Fair Work-SCHADS rule enforcement, non-production-gated data-reset.
• QA & testing: vitest unit/integration (Testcontainers-backed PostgreSQL), API smoke tests, typed-contract testing via OpenAPI/Orval, two-gate completion.

6. Capabilities & Expertise Demonstrated

• Solution architecture for a multi-sided marketplace → designed a broker-spine platform with adapter/strategy seams and a broker_org_id tenancy axis that absorbed AI matching and is multi-broker-SaaS-ready without rework.
• Enterprise / third-party integration with no APIs → mapped three different vendor acceptance models from operator evidence and designed an email-ingest + RPA + file-export archetype; built idempotent write-backs to Brevity, MYOB, QuickSuper and NDIS.
• Regulated payroll engineering → a SCHADS award engine (six-bucket penalty stack, eight-jurisdiction public-holiday calendar) and a locked pay-period → vendor-export → close lifecycle.
• AI / LLM product engineering → a provider-pluggable matchmaker (Claude / Gemini / OpenRouter) with rules-gating and explainable, UI-tunable scoring.
• Workflow & state-machine design → shift lifecycle (open → dispatched → accepted → delivered → paid), first-to-accept atomic claim, notice-tiered withdrawal, qualification/scope gating.
• Full-stack product & UX → coordinator console, nurse PWA and Expo mobile delivered from one typed API; data-driven in-portal discovery/verification tooling.
• Release engineering & ops → OpenAPI→Orval typed-contract codegen, esbuild bundling, systemd/nginx deploys, and a vendor-simulator fleet enabling full end-to-end demos with zero external credentials.
• Security & compliance engineering → RBAC + JWT + audit log; path-scoped authorization (caught and fixed a router-level guard leak); AHPRA / NDIS / SCHADS enforcement.
• Discovery & advisory → structured vendor discovery (Beeline, Staff Central, Brevity), a pilot-readiness methodology, and a go-to-market "auto-accept wedge" framing.

7. Hard Problems Solved / Innovations

• Three incompatible vendor acceptance models, none with an API. Discovery (reconstructed from operator screenshots) revealed Beeline as submit-a-candidate (an MSP/buyer shortlists), Staff Central as assign-your-own-employee (first-to-assign wins), and Brevity as a booking write-back. Solved with one shared ingestion + matching brain and per-portal write adapters, so "auto-accept" correctly becomes auto-submit on one portal and auto-assign on another — same engine, different last step.
• The supply-fill "master stroke." Instead of broadcasting a job inside Brevity (which created contention), CarePortal broadcasts to the top-ranked nurses outside the vendor, races the responses to a first-to-accept winner on its own side, and writes only the winner back into Brevity — turning availability capture into a flywheel rather than a data-entry chore.
• Award-accurate pay across Australian jurisdictions. A SCHADS engine with a six-bucket penalty stack and correct public-holiday handling across eight states/territories, including subtle legal-accuracy corrections (e.g. Queensland Easter-Saturday treatment and overtime-threshold semantics) — the kind of detail that determines whether a pay run is lawful.
• Reading demand + OTP without touching the client's mailbox. A mail-forwarding design copies only vendor-domain mail to a dedicated pilot inbox, read via the Gmail API over OAuth — deliberately chosen after empirically proving that Google now blocks basic-auth IMAP (and retired its unlock path) from data-centre IPs. The coordinator's mailbox and workflow stay untouched.

8. Outcomes & Impact

Measured (built & verified on staging). The full lifecycle runs end-to-end against the simulator fleet: a real shift was driven open → dispatched → AI-matched → accepted (nurse PWA) → clocked → SCHADS-awarded → delivered → pushed to Brevity; an award-computed pay run (≈ A$1,537 gross) was generated, exported to MYOB / QuickSuper and closed; vendor re-push was proven idempotent; incident reporting and roster/compliance views are operational. Delivery maturity: a working platform on staging — not yet in production.

Projected / to validate in pilot. The core value thesis — automatically submitting/assigning the best-matched available nurse within seconds of a shift email, around the clock, plus one-place roster + credential sync across portals and automated award pay — targets materially faster fill and higher shift-win rates than today's manual, multi-inbox race. These are modelled benefits, pending the live pilot now being set up. (Labelled as projected, not measured.)

9. Roadmap & Evolution

POC + hardening of the full pipeline → AI matchmaker → mobile + open-shift dispatch → structured vendor discovery (Brevity, Beeline, Staff Central) → supply write-back (against the simulator) → a real-data pilot via mail-forwarding + portal RPA (in setup) → multi-broker SaaS (architected from day one via broker_org_id, a future track). Each phase is a standalone, demonstrable increment — a land-and-expand path rather than a single big-bang build.