B prefix means: B1–B40 are the Backend system flows — capabilities the platform runs on its own, with no screen. They're the counterpart to the actor-facing capabilities in the System Map (aide AD-#, recruiter AR-#, operator OP-#, …), and a UI story points to the backend flow it kicks off with ⇢ B#. A candidate is never messaged without a consent check (B5) and every message is archived (B14) — those cross-cutting steps appear inside the flows that use them rather than as standalone diagrams.The case lifecycle, end to end
Updated 2026-08-19. The one flow that makes money — reframed around the discussion: there is no recruiter, the agency care coordinator drives it directly, patients are identified by case ID only, and integrity is monitored throughout. Every numbered component below zooms into one leg of this.
sequenceDiagram
autonumber
actor CC as Agency care coordinator
participant SYS as JobCare platform
actor C as Candidate aide
participant VEND as Twilio / Postmark / Stripe
CC->>SYS: post case (case ID only, no PII) (B1)
SYS->>SYS: match internal + external (B2)
SYS->>VEND: auto-blast availability to all internal matches, agency template (B3)
Note over SYS,VEND: standing consent covers it, STOP honored (B5)
C-->>SYS: reply available (B4)
SYS-->>CC: responses + ranked matches
opt not enough internal
CC->>SYS: request contact on external candidates
SYS->>VEND: contact external (B3)
end
CC->>C: follow-up questions via system (B14)
CC->>SYS: proceed with a candidate
SYS->>C: request missing docs + agency application (B21)
C-->>SYS: upload docs
CC->>C: price negotiation via system (B14)
CC->>SYS: schedule interview, contact released (B22)
CC->>SYS: log hiring decision within 24h (B23)
alt hired
SYS->>VEND: create invoice, fee by tier (B6)
CC->>VEND: pay (B7)
loop 7/30/60/90 days
SYS->>C: retention check-in (B9)
end
else no or missing decision
SYS->>SYS: flag case as suspect (B24)
SYS->>C: reach out, how is the job going (B24)
end
Note over SYS: every step writes event (B13) + archives msgs (B14)
sequenceDiagram autonumber actor S as Coordinator / agency participant PM as Postmark Inbound participant API as API route participant AI as Claude API participant DB as Postgres participant LOG as api_calls log S-->>PM: email to requests@jobcareus.com PM->>API: inbound webhook (raw email) API->>AI: extract job spec (role, geo, shift, conditions, pay, urgency) AI-->>API: structured fields API->>LOG: log call + cost (B15) API->>DB: create job (writes event B13) API->>API: hand to matching (B2)
sequenceDiagram
autonumber
participant API as API route
participant DB as Postgres
participant EXT as SourcingSearch port (providers: none configured in v1)
participant LOG as api_calls log
API->>DB: stage-1 filter (cert, geo, availability)
Note over API,DB: 8/24 - graded not strict-exact (adjacent certs, nearby ZIPs)
DB-->>API: eligible internal set
API->>API: stage-2 rule score (role+25, lang+20, cond+20, skill+15, rating, vetting, exp)
opt Coordinator asks, or matches are few (CC-4)
API->>EXT: search external sources
EXT-->>API: 0 providers configured (Null adapter) or the configured providers' candidates
API->>LOG: log each provider call + cost (B15)
end
API->>DB: persist merged, ranked match set
API-->>API: return shortlist (target under 90s)
sequenceDiagram
autonumber
participant API as API route
participant Q as Inngest job
participant CL as consent ledger
participant TW as Twilio 10DLC
participant PM as Postmark
participant COMM as comms archive
Note over API: internal match = auto on posting. external = only on coordinator request
API->>Q: enqueue outreach(candidate, case)
Q->>CL: check standing consent + STOP list (B5)
alt internal match, standing consent
Q->>TW: availability SMS, agency template + STOP-HELP
Q->>COMM: archive outbound (B14)
else external candidate, coordinator requested
Q->>PM: message with /join conversion link (B12)
Q->>COMM: archive outbound (B14)
else on STOP list
Q-->>API: suppress, flag do-not-contact
end
/join link (B12). Prototype "Send outreach now" is a no-op. Open question: how often the same aide may be re-contacted (frequency cap).
sequenceDiagram
autonumber
actor C as Candidate
participant TW as Twilio
participant API as API route
participant COMM as comms archive
participant CL as consent ledger
participant DB as Postgres
C-->>TW: reply (YES / STOP / free text)
TW->>API: inbound webhook
API->>COMM: archive inbound (B14)
alt YES
API->>CL: YES is an availability answer — consent already on file from sign-up (B5), never inferred from a reply
API->>DB: activate for matching, referral = contacted, availability = available (B32)
else STOP
API->>CL: record revocation (honored immediately)
API->>DB: exclude candidate from all outreach
else free text
API->>API: match message to existing conversation thread
API->>DB: referral = responded, route to coordinator
end
STOP is honored before anything else. Updated 8/24: free-text is correlated to its existing thread before routing; replies update availability (B32).
sequenceDiagram
autonumber
participant CALLER as Any outreach attempt
participant CL as consent ledger (append-only)
participant REG as 10DLC registry
Note over REG: registered before any production SMS
CALLER->>CL: may we contact candidate X on channel Y?
CL->>CL: latest consent state + STOP history + text version
alt valid consent on file
CL-->>CALLER: allow (attach consent record id)
else revoked or none
CL-->>CALLER: deny
end
Note over CL: opt-in captured with IP + timestamp + consent-text version - "consent is not a condition of service"
sequenceDiagram autonumber participant SRC as External sourcing provider (none configured in v1) actor C as External candidate participant WEB as /join/[token] participant API as API route participant DB as Postgres SRC-->>C: outreach with unique /join link C->>WEB: opens link WEB->>API: resolve token → prefill profile C->>WEB: complete signup + TCPA consent API->>DB: reconcile external record → internal member API->>DB: update source = converted, consent recorded (B5)
sequenceDiagram autonumber actor ADM as Coordinator / operator participant API as API route participant DB as Postgres ADM->>API: confirm hire API->>DB: create placement, determine fee by tier API->>DB: create invoice RECORD (accrual, unbilled) API->>DB: writes event (B13) Note over API,DB: not charged now - monthly statement aggregates + charges (B30)
sequenceDiagram autonumber actor AG as Agency billing participant ST as Stripe participant API as API route participant DB as Postgres AG->>ST: pay hosted invoice (ACH / card) ST->>API: payment_intent.succeeded webhook API->>DB: mark invoice paid, sync placement.invoiceStatus API->>DB: writes event (B13)
markPaid flips seeded invoices; no Stripe. Optional QuickBooks GL sync (v1) is a separate downstream job.
sequenceDiagram
autonumber
participant CR as Inngest cron
participant DB as Postgres
participant PM as Postmark
loop daily
CR->>DB: find invoices overdue 7 / 14 / 25 days
DB-->>CR: matches
CR->>PM: send reminder (escalating)
CR->>DB: log reminder event (B13)
end
sequenceDiagram
autonumber
participant CR as Inngest schedule
participant API as API route
participant TW as Twilio
actor C as Aide
participant DB as Postgres
Note over CR: scheduled at placement + 7/30/60/90 days
CR->>TW: "Still working at [Agency]? Reply YES/NO"
TW-->>C: SMS
C-->>API: reply
alt YES
API->>DB: retention confirmed → enables billing milestone
API->>DB: availability = on-placement (B32)
else NO
API->>DB: separation recorded (date, reason if given)
API->>DB: availability = available (B32)
else no reply
CR->>TW: retry once, then escalate to operator
else other / free text
API->>API: route to B4 thread-matching
end
API->>DB: writes checkin event (B13)
sequenceDiagram
autonumber
participant CR as Inngest schedule
participant DB as Postgres
participant ST as Stripe
CR->>DB: placement still active at 90d? (from B9)
alt retained
CR->>ST: create +$500 retention-bonus invoice
CR->>DB: writes event (B13)
else separated
CR->>DB: no bonus, note outcome
end
sequenceDiagram
autonumber
actor ADM as Operator
participant API as API route
participant DB as Postgres
participant ST as Stripe
ADM->>API: aide left placement
API->>DB: check expected term + MSA replacement policy
alt short-term placement ended as expected (e.g. post-op)
API->>DB: normal completion, no guarantee triggered
else within guarantee window
API->>DB: issue replacement credit toward next placement
Note over API: never a cash refund — keep the fee, give a substitute
else outside window
API-->>ADM: fee stands
end
opt genuine refund case
API->>ST: process refund
end
sequenceDiagram autonumber actor U as User participant CK as Clerk participant API as API route participant DB as Postgres U->>CK: sign in (password / magic link / Google-Apple) CK->>API: user.created / session webhook API->>DB: upsert user, map to role (7 roles) API->>DB: apply row-level-security tenant scope API-->>U: session with role claims (RBAC enforced server-side)
sequenceDiagram autonumber actor U as Authorized user participant API as API route participant DB as access log participant S3 as S3 (encrypted) U->>API: request vetting document API->>DB: authz check + write access-log row API->>S3: mint short-lived signed URL S3-->>U: file (link expires)
sequenceDiagram autonumber participant ANY as Any mutation / message / vendor call participant EV as events (append-only) participant COMM as communications participant COST as api_calls ANY->>EV: B13 — actor, entity_type, entity_id, details, ts ANY->>COMM: B14 — body, direction, channel, referral link (never deleted) ANY->>COST: B15 — request, response summary, timing, cost Note over EV,COST: any entity's full history reconstructible from events
sequenceDiagram autonumber participant CR as Inngest schedule participant DB as Postgres (placements, events) participant PROF as agency_preferences CR->>DB: read placement history per agency CR->>CR: derive patterns (years, languages, conditions, rejections) CR->>PROF: write transparent, adjustable weights Note over PROF: surfaced to agency, used as ranking signal - rules-based (LL144-safe) — no ML until 1,000+ placements
sequenceDiagram autonumber participant API as Event source (e.g. matches ready) participant HUB as notification hub participant PREF as user prefs participant CH as in-app / Postmark / Twilio API->>HUB: notify(user, type, payload) HUB->>PREF: channels enabled for this type? PREF-->>HUB: e.g. email + in-app HUB->>CH: deliver on each channel Note over HUB: works even when the user is logged out
sequenceDiagram autonumber participant P as Partner agency participant API as POST /api/v1/jobs participant RL as rate limiter participant SYS as match pipeline participant WH as webhook P->>API: submit job (API key) API->>RL: check key + limits RL-->>API: ok API->>SYS: run B1/B2 pipeline SYS->>WH: POST matches to partner callback URL WH-->>P: matches delivered
Case-lifecycle flows added 2026-08-19
B21–B24 come from the 8/19 discussion — the stages from "proceed with a candidate" through the interview and the anti-fee-leakage monitoring.
sequenceDiagram autonumber actor CC as Care coordinator participant SYS as API route participant DB as Postgres actor C as Candidate aide participant S3 as S3 encrypted CC->>SYS: proceed with candidate SYS->>DB: check which docs already on file SYS->>C: request ONLY missing docs, licenses, certs, tests + agency application C->>S3: upload documents (B17) S3-->>SYS: stored, access logged SYS->>DB: mark vetting items received, pending confirmation SYS-->>CC: docs in, ready to confirm
sequenceDiagram autonumber actor CC as Care coordinator participant SYS as API route participant DB as Postgres actor C as Candidate aide Note over SYS: gate = docs confirmed in order CC->>SYS: request interview with patient family SYS->>DB: release candidate contact info to coordinator SYS->>C: propose interview slots C-->>SYS: confirm slot SYS-->>CC: interview scheduled Note over SYS: start 24h decision clock (B23)
sequenceDiagram
autonumber
participant CR as Inngest timer
actor CC as Care coordinator
participant SYS as API route
participant DB as Postgres
Note over CR: 24h after scheduled interview - preferred route = agency updates us
alt agency logs decision in time
CC->>SYS: record hired / not hired
SYS->>DB: update case + placement
SYS->>DB: if hired, availability = on-placement (B32)
else no decision by 24h
CR->>SYS: escalate, remind coordinator
SYS->>DB: flag case for integrity review (B24)
Note over SYS: fallback - ask the aide directly (B24)
end
sequenceDiagram
autonumber
participant SYS as integrity monitor
participant DB as Postgres
actor C as Candidate aide
actor OP as JobCare operator
SYS->>DB: scan each case ID
alt multiple candidates reached application but no aide found
SYS->>OP: flag suspect (possible hidden hire)
else interview scheduled but no response
SYS->>OP: flag suspect
SYS->>C: reach out, how is the job going
C-->>SYS: reply
SYS->>DB: reconcile, if placed then trigger billing
end
Onboarding flow added 2026-08-23
B25 is the Prospect side of AA-4: turning an agency's bench list into consented JobCare Members, with the submitting agency earning priority.
sequenceDiagram
autonumber
actor AO as Agency (submits bench)
participant SYS as JobCare platform
participant DB as Postgres
participant TW as Twilio / Postmark
actor A as Prospect
AO->>SYS: submit bench list (name, phone, email, cert)
loop each listed person
SYS->>DB: dedup check against existing records
alt genuinely new person
SYS->>DB: create Prospect record, source = agency_bench
SYS->>TW: invite to register (agency template + consent)
A-->>SYS: open /join link, register
A->>SYS: give consent + stated certifications + availability
SYS->>DB: activate Member, set submitting-agency priority (90d)
else already in system OR listed by multiple agencies
SYS->>DB: flag for priority-collision handling
Note over SYS,DB: OPEN QUESTION - who gets priority
end
end
Flows added 2026-08-24
From the 8/24 review: Member sign-in is covered by B16; these seven cover credentials, uploads, the MSA, match-on-signup, monthly billing, how a Member sees matches, and the availability lifecycle.
sequenceDiagram
autonumber
participant CR as Inngest cron
participant DB as Postgres
participant N as Notification hub
actor M as Member
loop daily
CR->>DB: scan certs, in-service hours, HHA currency
alt expiring in 60 / 30 / 14 days or hours short
CR->>N: nudge Member (B19)
N->>M: reminder to renew / log hours
CR->>DB: flag for operator if lapsed
end
end
sequenceDiagram autonumber actor M as Member participant API as API route participant S3 as S3 (encrypted) participant DB as Postgres M->>API: upload document (license, cert, test result) API->>S3: store encrypted (KMS) S3-->>API: object key API->>DB: record document + credential = under review (operator verifies, OP-2) API->>DB: access-log entry (B13)
sequenceDiagram autonumber actor AA as Agency Admin participant API as API route participant DS as Dropbox Sign participant DB as Postgres API->>DS: send MSA template (prefilled) DS->>AA: sign request AA->>DS: sign DS->>API: completion webhook API->>DB: store signed PDF, mark MSA signed Note over API,DB: unblocks placement + billing (AA-3)
sequenceDiagram
autonumber
actor M as New Member
participant API as API route
participant DB as Postgres
participant N as Notification hub
M->>API: complete registration (PR-1/PR-2/PR-3)
API->>DB: match against open cases (B2)
alt matches found
API->>N: notify agency and/or Member (B19)
else none
API->>DB: hold in pool for future cases
end
sequenceDiagram autonumber participant CR as Inngest monthly participant DB as Postgres participant ST as Stripe participant PM as Postmark actor AA as Agency Admin CR->>DB: gather the month's accrued invoice records per agency (B6) CR->>DB: build one statement per agency CR->>ST: charge statement (ACH pull / card) CR->>PM: email statement + receipt ST->>DB: payment webhook → mark paid (B7) Note over CR,DB: overdue statements → reminders (B8)
sequenceDiagram
autonumber
participant SYS as JobCare platform
participant N as Notification hub
actor M as Member
participant API as API route
alt push
SYS->>N: match ready → notify (B19)
N->>M: email / SMS / in-app
else pull
M->>API: open portal/app, browse open jobs
opt not marked available
API->>M: prompt to update availability (B32)
end
end
M->>API: express interest / respond to availability
API->>SYS: create referral / update case
sequenceDiagram
autonumber
participant SRC as Any source
participant DB as availability state
Note over SRC,DB: one place changes availability
alt Member self-update (MB-1)
SRC->>DB: set available / not
else prompted while browsing (B31)
SRC->>DB: confirm still available
else reply-derived (B4 / B9 / B23)
SRC->>DB: YES→active, hired→on placement (STOP goes to the consent ledger / send gate, B5 — not a state)
else dormancy timer
SRC->>DB: active → passive → dormant over time
end
Flows added 2026-08-26 (from the coverage audit)
B33–B37 close gap items the audit surfaced — revenue lines, the aide-referral channel, and the connector framework.
sequenceDiagram autonumber actor AG as Agency participant API as API route participant DB as Postgres AG->>API: request a verified vetting packet (no placement) API->>DB: confirm packet verified (B27) API->>DB: create invoice record, type = vetting_packet Note over API,DB: rolls into the monthly statement (B30)
sequenceDiagram autonumber actor AG as Agency participant API as API route participant DB as Postgres participant TW as Twilio actor C as Former employee AG->>API: reactivate [named aide] API->>DB: find record + check consent/STOP (B5) API->>TW: re-engagement outreach (STOP/HELP) C-->>API: responds API->>DB: reactivate, create invoice record ($100-300)
sequenceDiagram autonumber participant CR as Inngest monthly participant DB as Postgres participant ST as Stripe CR->>DB: agencies with an active data subscription CR->>DB: compile market-intel report (from B18 learning) CR->>ST: charge subscription ($200-500/mo)
sequenceDiagram autonumber actor M as Member (referrer) participant API as API route participant DB as Postgres actor F as Referred friend M->>API: refer a friend (name, phone) API->>DB: create Prospect, source = referral, referred_by = M API->>F: invite to register (consent B5, /join B12) Note over API,DB: on the friend's first placement, credit M's incentive
sequenceDiagram autonumber participant SRC as Source adapter (job boards / resume databases / multi-post / ATS / CSV — none configured in v1, mock provider for the demo) participant API as connector interface participant DB as Postgres SRC->>API: fetch/import candidates (per-source adapter) API->>DB: dedup + upsert as Prospects (source tagged) Note over API: one interface, many adapters - add a source without touching call sites API->>DB: CSV bulk export on demand
Flows added 2026-08-27
B38–B39 cover the AI-agent question handling and non-matched interest paths.
sequenceDiagram
autonumber
actor C as Candidate
participant API as API route
participant AI as AI agent
participant DB as Postgres
actor CO as Coordinator
C-->>API: free-text question
API->>DB: match to conversation thread (B4)
API->>AI: can this be answered from the job post?
alt answerable (pay / location / shift / start)
AI-->>C: auto-reply (STOP/HELP)
API->>DB: log ai_handled
else needs a person
API->>CO: notification + queue entry (B19), with full thread + job post
end
sequenceDiagram
autonumber
actor M as Member (not on the match list)
participant API as API route
participant DB as Postgres
actor CO as Coordinator
M->>API: express interest in a job post
API->>DB: create referral (source = self-interest), start a conversation thread
API->>API: run the same intake as any response (B38)
alt AI can handle
API-->>M: auto-reply
else
API->>CO: notification + queue entry (B19) with the thread + job post
end
Flows added 2026-10-21
B40 is the roster-invitation path decided in the tech-stack review (ADR-0002 Amendment 1): an agency's roster rows are invitations, not aides — one agency-branded text, and the person enters the pool only by signing up and consenting to JobCare directly.
sequenceDiagram
autonumber
actor AA as Agency admin
participant APP as JobCare app
participant DB as Postgres
participant SMS as Twilio 10DLC
actor P as Person on the roster
AA->>APP: upload or paste the roster (name, phone, zip, credential)
APP->>APP: promote name, phone, zip, credential; capture every other column raw in roster_import_rows, read by nothing (David, 2026-11-10)
APP->>DB: dedup by E.164 phone vs Members, this agency's own open invitations, suppression hashes
APP-->>AA: preview — new / already a Member / already invited / opted out
AA->>APP: send invitations
APP->>DB: insert roster_invitations (batch_id, status=pending)
loop each invitation
APP->>SMS: ONE agency-branded SMS with the sign-up link (consent-gated send path, B5)
APP->>DB: status=sent, sent_at (B13 event, B15 cost row)
end
alt person replies STOP
SMS->>APP: inbound STOP
APP->>DB: status=stopped, HMAC(phone) written to the suppression list (B4/B5)
else person signs up (PR-4)
P->>APP: open the link, confirm details, consent to JobCare, verify phone (OTP)
APP->>DB: create Member (source=roster_invite, provenance=inviting agency), consent ledger row (B5), status=signed_up
else no answer for ~90 days
APP->>DB: purge the row, keep HMAC(phone) as the no-re-invite key
end