How to read this
Each card is one coarse capability — an actor's task, or something the system does on its own. It carries a short description and, where relevant, the backend flow it uses. A build-status tag shows how far along it is.
requirements.md §2b, and stamped here by build:docs — edit it there, not on this page. Families are out of v1 but stay on the map and in the Explorer.docs/requirements/requirements.md) so this map stays a clean, first-look picture of what the system does.Actors at a glance
Seven human actor types. The pivotal one is the agency care coordinator — with no recruiter in the loop, they drive the whole case lifecycle directly against the system. JobCare staff are just the operator (running the business) — not a per-case human making matching decisions. The person-actors (Prospect, Member) are named role-neutrally so the platform can extend beyond aides later.
| Actor | In one line | Pays? | Tasks |
|---|---|---|---|
| Prospect | A person we know of (from an agency roster or bench list, an external site, or their own outreach) who has not registered yet | Free | 4 |
| Member | Registered to receive job offers; we hold a full profile — certifications, background checks, reviews, availability | Free | 11 |
| Agency Admin | Sets up the agency, signs the MSA, invites its roster, configures outreach policy + template, manages staff, sees & pays invoices | Yes | 7 |
| Agency care coordinator | Drives the case lifecycle directly: post case, review matches, message, proceed, schedule, decide, work the response queue | — | 12 |
| Family | Household hiring an aide directly, or the family of a patient an agency serves (they rate the aide) | Yes (less) | 5 |
| JobCare operator | Runs the business from the admin cockpit + monitors case integrity + revenue lines & compliance | Staff | 16 |
| Partner (API) | Integrated agency submitting jobs programmatically (Phase 5) | Yes | 1 |
Prospect known to us · not yet registered
The top of the supply funnel: a person we know about but who hasn't registered. They arrive three ways — they sign themselves up, we surface them from an external site, or an agency lists them from its bench. Growing this into registered Members is an explicit product goal.
Self-signup: name, phone, email, cert, location (City / State / ZIP), work types, languages — with an optional TCPA SMS-consent checkbox, unticked by default and never a condition of joining (wording version 1, ADR-0014: “By checking this box I authorize JobCare to send me automated text messages at the number I provide, on behalf of the home-care agencies I am matched with, about care jobs that match me, interviews, documents and check-ins. Message frequency varies. Message and data rates may apply. Agreeing is not a condition of joining JobCare or of any referral. Reply STOP to end texts at any time, HELP for help. Sign-in codes and STOP confirmations are sent only on request. Terms and privacy: jobcareus.com/terms.”); without it the aide is reached by email and in-app only. On registering, a Prospect becomes a Member.
A person first surfaced by an external sourcing provider (none configured in v1; the interface ships with a mock provider) follows a personalized link that pre-fills their profile, turning an external record into a registered, consented Member.
A person an agency lists from its bench is a Prospect to JobCare — they have a relationship with the agency, not with us. They must register so we capture consent + certifications + availability. Stated creds start matching; proof needed before finalizing. The submitting agency then earns priority. Aide-side view of AA-4. For v1, superseded by the roster invitation (PR-4 / AA-7 / B40): nobody enters the pool before signing up, and the inviting agency gets provenance plus a first-choice window from roster receipt (requirements §3, ADR-0002 Amendment 2).
Added 2026-10-21 (ADR-0002 Amendment 1). A person on an agency's roster receives one agency-branded text inviting them to sign up at JobCare. The link opens a sign-up pre-filled from the invitation (name, phone, ZIP, credential); they consent to JobCare directly (phone verification + consent ledger) and only then enter the pool. The inviting agency is recorded as provenance on the Member, with a first-choice window: for W days from the day JobCare received the roster, that agency's cases reach this aide first (ADR-0002 Amendment 2, 2026-10-22); afterwards the aide is matched like any other Member. Aide-side of AA-7.
Member registered · has a full profile
A person who has registered to receive job offers and about whom we hold real data — certifications, background checks, reviews, availability. The core work here is sign-in, document upload, consent, keeping availability current, and the communication loop.
Members sign in to reach their profile, matches, and messages with a six-digit code JobCare texts to their phone; the code is sent on request even to an aide who has stopped texts (ADR-0014). The device stays signed in for thirty days, the code re-enters, and there is no password. A lost phone with a new number is recovered by a signed link to the email on file, otherwise by an operator re-proof on a live call (ADR-0015).
Contact, location (City / State / ZIP) and time zone (quiet hours for texts follow it), certifications with number + expiration, experience, specializations, languages, preferred language (English or Spanish, chosen on the join form and editable here; never inferred from a reply and never a matching input; it picks the language of the texts and, later, the screens; ADR-0023), transportation, pay floor — and, importantly, keep their availability status current (it drives whether we contact them).
Upload photo ID, TB, physical, immunizations, CPR, certificates, references and résumé (no I-9: an employer's form, removed by ADR-0013). Files stored encrypted; every access logged. The verification record travels with the Member across agencies (the moat). Kept as files after verification: certificates, licences, CPR cards, the résumé. Result only, file deleted at verification: identity scans, TB test, physical, immunizations, references, registry. Never a file: the background check (status, vendor, report id, date). Decided 2026-11-09 (ADR-0018): every result is one recorded row with its source (operator, agency, later a vendor) and the supplying agency; the background check and the exclusion lists are the agency's, recorded as "agency reports cleared" with the date, never a check JobCare ran.
SMS opt-in (box unticked by default), email preferences, and packet-sharing consent per referral. How to reach me (ADR-0014): “In the app first, text me if I haven't seen it” (default) or “Always text me right away”. Each channel is stopped on its own: a texted STOP stops texts only, an email unsubscribe stops email, the in-app toggle stops notifications while threads stay readable; “stop contacting me” in any words stops everything. Every consent change is archived immutably. The send gate checks consent per channel and on whose behalf a message goes out, applies quiet hours in the aide's own time zone, and keeps one counter per message purpose (limits not yet set).
Two ways: push — we notify them when a match appears (B19); pull — they open the portal/app and browse (B31). They respond to the availability request; the agency coordinator decides who to advance.
See where each expressed-interest job stands. Read-only view — no backend flow needed (convention: flows are only for boundary-crossing actions).
Answer outreach and retention check-ins at 7/30/60/90 days in the app, or by replying to the text (YES/NO/STOP). Responses update the Member's availability. A texted reply carrying the thread's code does whatever the aide's own tap on that thread does: confirm interest, confirm or decline an interview, answer a check-in or a question. Contact release and the hire record are the coordinator's actions; each sends the aide a receipt (“Not you? Reply NOT ME”) and an operator can reverse the release (ADR-0014). A texted STOP stops texts only.
Continuing-education tracking required by NY law (HHA 12 hrs/yr, PCA 6 hrs/yr) with certificate upload; also the HHA "≥16 hrs of work every 2 years or the cert lapses" rule. Alerts before deadlines.
Composite score + tier (Gold/Standard/Watch/Unrated) + individual reviews from past placements.
A Member refers another aide; the referral is tracked and the referrer earns an incentive on a successful placement. The referred person enters as a Prospect (source = referral) — the highest-quality, lowest-cost supply channel.
A Member who wasn't on the matched list can still raise their hand for a job. It follows the same path as any response — a rule-table answer handles simple questions about pay, place, shift or start, otherwise it goes to the coordinator's queue.
Agency Admin the paying customer · setup, contract & billing
Owner and billing are one actor — how an agency divides admin work internally isn't our concern. This is everything that makes an agency a contracted, billable customer: sign-in, profile, MSA, bench, and invoices.
Invite-only accounts; invite and remove staff (e.g. care coordinators). JobCare sends the invitation under its own brand. Every seat sets up a second factor on acceptance: an authenticator app, a passkey or a texted code; an agency may sign a waiver reducing this to admins only. Roles Agency admin and Coordinator in v1, Billing and Viewer when an agency asks (ADR-0015).
Licenses (LHCSA/CHHA/LTHHCP/Hospice/FI-CDPAP), NPI + Medicaid/Medicare provider IDs, insurance, authorized counties, services, patient conditions handled, worker types, payer mix, hiring volume, pay ranges.
Click-to-sign in product: the signed-in agency admin agrees to MSA version N, including the 12-month long-tail introduction clause and the replacement-not-refund policy. Document hash, account, email, IP and time are recorded and a copy is emailed; placement/billing blocked until signed. A vendor e-signature (B28) comes later.
Batch-upload overflow aides with a consent choice — JobCare texts each for opt-in, or the agency attests to existing written consent. The agency's own jobs see their bench first for 90 days. Each listed person is a Prospect who must register (PR-3). For v1, superseded by AA-7 / B40: a roster row is an invitation, never a pool entry, and the agency gets provenance plus a first-choice window from roster receipt (requirements §3, ADR-0002 Amendment 2). Since 2026-11-10 (David): the upload accepts every column; name, phone, ZIP and credential are promoted and every other column is captured raw, read by nothing, until David decides what to promote (story AA-4.1).
Performance scorecard, every figure live and labelled "as of now" (placements, paid to date, retention at 30 / 60 / 90 days, MSA status; a dated footnote for ninety days when a definition changes — ADR-0019); the agency-scoped invoice/statement list with aging; and pay JobCare via Stripe (ACH preferred, card accepted).
The score thresholds that decide matching: auto-contact aides at/above one score, show for the coordinator to decide in a middle band, and cap how many are auto-contacted per case. In v1 these are fixed defaults the agency can read but not change; the outreach message template is JobCare's fixed wording with the agency name interpolated.
Added 2026-10-21 (ADR-0002 Amendment 1). Upload or paste the agency's roster — name, phone, ZIP and credential type are promoted into the invitation; since 2026-11-10 (David) every other column is captured raw in roster_import_rows (nothing for an opted-out person), read by nothing, and the preview names it as "captured for later, not yet used". The platform de-duplicates by phone (already a Member, already invited by this agency, or opted out), shows the preview, then sends each person an agency-branded SMS on the agency's behalf, under the agency's consent on file, inviting them to sign up. Status per row: pending → sent → signed up / stopped. Unanswered invitations are purged ~90 days after the send; only a keyed hash of the phone is kept. Imported rows are invitations, not aides — this replaces the "CSV bulk import" idea. JobCare sends the SMS as the agency's vendor (operational notice; ADR-0004, 2026-10-22). First-choice window: for W days from receipt of the roster the agency has first choice on the aides it introduced when they match several agencies' cases (equal preference if an aide comes from several rosters); the Roster tab shows the window per batch (ADR-0002 Amendment 2).
Agency care coordinator the daily driver · works the system directly, no recruiter
There is no recruiter — the agency's care coordinator runs the whole case lifecycle directly against the system. The cards below are that lifecycle, in order.
Post a job request with as much detail as possible (role, location as City / State / ZIP, shift, requirements), identifying the patient by case ID# only — no PII. Chip form or pasted email, both feeding one spec. Updated 2026-10-27 (ADR-0012): each requirement can be marked required or preferred. Only a credential, a language, a skill with a safety basis and the radius may be required; a required one becomes an eligibility fact, a preferred one keeps its points. The radius comes from the agency policy (default 25 miles) and the coordinator may tighten it for the case. When the required marks would leave fewer eligible aides than the agency's show cap, the form says so before posting.
On posting, the system automatically sends an availability request to every internal match — using a fixed JobCare template with the agency name interpolated (agencies do not edit wording) + basic requirements. No one is auto-rejected, which keeps ranking decision-support (LL144-safe).
See the ranked internal matches with transparent reasons, availability + reputation, prior-placement history, and who responded "available." 2-stage match is real client-side (filter + additive rule score). Updated 2026-10-27 (ADR-0012): the shortlist sorts by best match (the stored rank, the default), distance, years of experience, availability or internal first; a sort is a view of stored facts, never a second score. Eligible aides below the show score are folded, not hidden: a count and a "show more" that pages by rank.
The pool is always searched first. When matches are too few, or on request, the result area offers Search external sources and Post a job ad: both are ports with no provider configured in v1 (ADR-0005, 2026-10-22; no vendor offers a candidate-search API, scraping is out). Once a provider is configured, external candidates are shown and contacted only when the coordinator requests it.
Ask candidates additional questions via the system — the coordinator does their own screening through system-mediated messaging (no JobCare recruiter in between). Every message archived.
Once ready to go ahead with a candidate, the system requests all required docs / licenses / certs / tests — only those not already on file — plus the agency application. This is deferred vetting made concrete. The base set has no I-9 (an employer's form, ADR-0013). The operator verifies every item; the coordinator sees each item's status, expiry, verifier and date — never a file, and verifies nothing. The agency receives certificates once, at the logged hire. Decided 2026-11-09 (ADR-0018): the background check and references are agency-reported results recorded with their source and agency, and the coordinator sees the background-check status only after a conditional offer; the word "verified" is provisional until counsel answers.
Price negotiation may occur at the proceed stage. All communication via the system (keeps the record + the fee defensible).
Once docs are confirmed in order, schedule the interview with the patient's family via the system. Candidate contact info is released to the coordinator at this point.
The coordinator MUST update the system within 24 hours of a scheduled interview with the final hiring decision. Enforced + escalated; feeds integrity monitoring.
The coordinator confirms the placement outcome and may give feedback. Note (8/24): the star rating that feeds an aide's reputation comes primarily from the family who received the care — even for agency placements (see FM-4/FM-5) — not from the agency.
Save a common opening as a template and post it repeatedly (e.g. a standing weekend-HHA need), instead of retyping each time. Distinct from the agency outreach template.
When an aide replies, the coordinator is notified immediately if online, and everything waits in a queue for next login otherwise. Opening a notification shows the message, the job post it relates to, and the full conversation (including the automated messages). AI-handled questions are answered without bothering the coordinator; the rest land here. Per-event email only in v1; daily digests later. The coordinator's email footer links to notification settings, never an unsubscribe; send-failure and billing notices cannot be switched off (ADR-0014).
Added 2026-09-04. A dedicated My open cases screen: every open case for the agency, with responses at a glance (applicants / responded / available) and a “needs your reply” count surfacing candidate questions waiting on the coordinator. Filter to just the cases awaiting you. Fills a gap — there was previously no screen to see all open cases.
Added 2026-09-04. Brings the conversation concept — built for aides — to the coordinator: one open case → many candidate threads, each showing status and whether it awaits your reply. Open a thread to read the question and answer it (one-tap contextual answers or free text); the reply lands in the aide's in-app thread, archived to the case, and a text goes out only if the aide hasn't seen it; the thread shows a “texted · delivered” chip when it does. This is where the SMS deep link jobcareus.com/c/<ref> resolves for the coordinator. Mirrors the aide’s MB-6 Messages.
Family hires directly, or is the patient's family on an agency placement
Two roles: a household hiring an aide directly, and — new emphasis (8/24) — the patient's family on an agency placement, because we want the family to rate the aide even then. Smaller feature set focused on the care-recipient profile, household-employer acknowledgments, and rating.
Account creation captures referral-only positioning + household-employer legal acknowledgments (limits JobCare liability).
Age, conditions, mobility, cognitive status, ADLs, schedule, budget, funding source.
Same match engine and contact-request flow as agencies.
Browse candidates, rate a placed aide, optional referral to a payroll partner (HomePay/GTM/Poppins).
Clarified 8/24: the family rates the aide even when the aide was placed through an agency (not the agency). For families who come to us directly, the requester simply gets the link.
JobCare operator the admin cockpit · runs the business
JobCare's own team runs the business from one cockpit — money, placements, the candidate database, conversations, and compliance.
Collected this month, by payment date, outstanding AR with overdue derived from the due date, active placements, completion rate (ended complete over ended), alerts, supply/demand, recent activity — every tile a live query from one figure catalogue, labelled "as of now"; no cache, no stored figure (ADR-0019).
Search/filter table; edit, merge duplicates, flag issues, bulk actions. An aide who lost their phone and has no email on file is re-proved here with a government ID shown on a live video call, never by profile facts (ADR-0015).
Track NY Home Care Registry status (Yes/No/Unknown) and refuse to refer any aide marked "No" — a hard legal rule agencies must obey. Decided 2026-11-09 (ADR-0018): the registry and licence checks are operator recordings from the public website, with their source and date, since no lookup interface exists; one record command (OP-3.2) records every vetting result, and nothing is automated.
Kanban of referrals by outcome; drag-to-update, manual notes; rejected-with-reason returns candidate to Available.
Active + ended placements; trigger or view scheduled check-ins (7/30/60/90) that double as billing verification.
Per-agency placements, revenue, retention, outstanding AR, MSA status.
Invoice generation, payment tracking, aging, refund workflow, mark-paid override, Stripe reconciliation; retention-bonus + replacement-credit logic.
Every SMS/email/WhatsApp thread across all referrals, filterable by candidate/agency/job/channel, never deleted.
Append-only event feed with type filters and export, opened from a case, an aide or an agency as well as on its own. Names are joined live, so after a purge a line reads "member removed" with the id. An agency's view of its own staff's activity comes later, on an agency's ask (ADR-0016).
Per-agency preference profiles derived from placement history ("you hire Spanish speakers 70%…"), transparent and adjustable — the LL144-safe alternative to ML.
Add/remove JobCare staff in two roles, operator and operator admin, with a break-glass recovery for the last admin (ADR-0015); and track complaints filed against aides as a distinct entity (beyond ratings/red-flags).
One operator queue, three lanes: business (a hidden-hire signal, a decision overdue, a roster re-appearance), security, and failed background work, ordered by severity, fee at stake, then age. Each signal keeps its own verdicts, and a confirmed hire still flows to billing. Six breach signals reach David by text and email from the cloud's own alarms; everything else is email or a weekly digest (ADR-0016).
Charge an agency $150–$400 for a verified vetting packet even without a placement — a pure-margin revenue line. Billing today only fires on hire (B6). Refined 2026-11-09 (ADR-0018): a background-check vendor waits for a signed vetted-tier contract, counsel's answer on the consumer-report question and the vetting fee live; it then arrives in the agency's name, and JobCare never orders a check itself.
Two more revenue lines: reactivation — locate & reconnect a specific former employee at an agency's request ($100–$300); and a market-intelligence subscription ($200–$500/mo/agency) once enough data exists.
The sourcing ports (SourcingSearch, JobAdPublisher) with their provider registry — no provider configured in v1, a mock provider for the demo and tests (switchable here) — plus CSV bulk import/export. Connector types a provider may plug in later: job boards, resume databases, multi-post distributors, ATS piggyback (ADR-0005, 2026-10-22).
Track the business/regulatory obligations the map otherwise left invisible: SHIELD Act safeguards, agency non-solicit limits on bench sharing, Employment-Agency-License ops (filed fee schedule, $5k bond, premises inspection), principal fingerprinting, and the zero-findings KPI: a finding is an outside party's adverse determination (regulator notice, demand letter or suit, carrier campaign suspension, a breach notice JobCare had to send), hand-entered and counted in three categories (texting, security, LL144), shown as "findings: zero" with system-computed leading indicators beside each (ADR-0019). Also the founder non-compete / data-provenance rule.
Partner agency (API) Phase 5 · programmatic
with API-key auth; matches returned via webhook subscription. Rate-limited, abuse-monitored.
Backend system functions no portal · the machine behind the actors
The "main backend system functionality" you asked to surface. Each is a capability the system runs on its own; each is a sequence diagram in the Flow Atlas. Cross-cutting ones (B13–B15) run inside almost every other flow. B21–B24 (case lifecycle, 8/19); B25 (agency-bench onboarding, 8/23); B26–B32 (credentials, upload, MSA, match-on-signup, monthly billing, member match views, availability — 8/24); B33–B37 (standalone vetting fee, reactivation, market-intel subscription, aide-referral, connector framework — 8/26, from the coverage audit); B40 (roster invitation — 10/21, ADR-0002 Amendment 1).
The agency's email arrives in the system directly; only a sender on file that passes the mail provider's authentication checks is read, anything else is quarantined to the operator queue unread. Decided 2026-11-08 (ADR-0017): the keyword parser fills every closed-list field first, conditions become the form's own tokens and identifiers are stripped, so only the leftover text reaches the model (Amazon Bedrock, retention mode none, the model a setting), which fills the free-form fields. The draft lands in the coordinator's inbox to confirm or discard. Explorer: the paste box simulates an arriving email. Decided 2026-11-09 (ADR-0018): the case email arrives by storage drop into our own bucket at one address for every agency, and a quarantined message's body is deleted at once, never released.
Stage-1 filter + stage-2 rule score, internal + external ranked. Internal matches are all surfaced (no auto-reject). Decided 2026-10-27 (ADR-0012): stage 1 is graded (adjacent credentials at reduced points, passive and dormant aides reachable) plus the case's required criteria and a radius; the score only orders, never excludes. Location is ZIP distance: straight-line miles between ZIP centroids in four bands (0–5 miles 12 points, 5–10 miles 8, 10–20 miles 4, beyond 0 with a "far" concern); the policy radius (default 25 miles) widens to 50 then 100 miles when fewer aides than the show cap are found; live-in cases ignore distance. Borough area and neighborhood are no longer matching inputs. Proto: internal real, external faked.
Updated 8/19: internal matches get an automatic availability blast using the agency's template (standing consent covers it); external candidates are contacted only on coordinator request. SMS (10DLC) and email through the providers chosen in ADR-0014, every message archived. The aide's primary channel is in-app: the text is the notification (the knock), sent when the message is still unseen after the purpose's delay, carrying a 72-hour tokenised https deep link to the thread; an aide who chose “Always text me right away” gets every text at once.
Reply YES/NO/STOP → update consent + referral state (STOP honored immediately, texts only) and update availability. Routing has no clock and no matcher (ADR-0014): the thread's reply code decides when present, else the one thread awaiting the aide, else one “Which case?” text listing each waiting case with its own code. A coded reply may do what the same tap does, contact release and hire confirmation included, with a receipt text and an operator reversal. Free text with no single thread goes to the operator inbox.
Append-only consent records (IP, timestamp, text-version); 10DLC registration; STOP/HELP; "consent not a condition of service"; the SMS box unticked by default; at most 8 texts a day per phone, sign-in codes and STOP confirmations not counted, quiet hours 8 am to 9 pm. Revocation is per channel (ADR-0014): a texted STOP revokes texts, an email unsubscribe revokes email, the in-app toggle stops notifications; a plain-language “stop contacting me” or account closure revokes every channel.
Updated 8/24: hire confirmed → placement → fee by tier → create an invoice record (accrual). It is not charged immediately — a monthly statement (B30) aggregates and charges.
Stripe webhook → mark paid → sync placement → write event.
Inngest-scheduled reminders at 7/14/25 days overdue — now against the monthly statement (B30), not per-placement invoices.
Scheduled 7/30/60/90-day SMS; aide YES/NO confirms retention — the billing source-of-truth. Updated 8/24: handles no-response (retry then escalate) and non-YES/NO replies (route to B4), and updates the aide's availability on the answer.
At 90-day retention milestone, generate the +$500 bonus invoice.
Within the guarantee window, credit toward a replacement — never a cash refund. differentiate by expected term — post-op placements are often short-term, so a short-term ending shouldn't trigger the same guarantee as a long-term placement ending early.
/join/[token] signup reconciles an external record into a consented Member; source updated. Waits for a configured sourcing provider (ADR-0005); the provider's terms of service bind the conversion path.
Every command writes an append-only event (actor, entity, ids-only details), plus a deploy event at every start. The record is copied out every day to a locked bucket in a separate account, each day's manifest chained to the last, so a missing or altered day shows. Any operator admin can place a legal hold on a case or a person (ADR-0016). Proto: seed-only.
Every message stored with body/ts/direction/channel, one row per delivery, in a thread tied to its object (a case, a check-in, an invitation, or the person's own notices; ADR-0014). Every in-app notification is a tracked row with its own read state, so one query answers what we told a person, on which channel, and whether they saw it. Searchable, never deleted.
Every vendor call (LLM, sourcing providers, messaging, payments) logs request, response summary, timing, cost.
JobCare issues every session from its own signing key; a hosted provider only proves staff and operator identity, and aides have no record at any vendor. Provisioning reads JobCare's own invitation token, with no identity webhook; RBAC enforced server-side; row-level security for tenant isolation (ADR-0015).
Vetting docs via sixty-second presigned S3 URLs, minted only after the access-log row; encrypted at rest, every access logged. Aides read their own files, operators by role; coordinators read no files, only verification status (ADR-0013).
Derive per-agency preference profiles from placement history; feed ranking; keep transparent + adjustable.
Multi-channel hub (in-app bell / email / SMS) with per-user preferences; notify-before-login. Every bell item is a tracked message row with its own read state. Coordinators get notification settings, not an unsubscribe: no coordinator message is under consent, and send-failure and billing notices have no off switch (ADR-0014).
POST /jobs → match → webhook callback; API-key auth, rate limiting, abuse monitoring.
On "proceed", request only the docs/licenses/certs/tests not already on file + the agency application; collect via secure upload; operator confirms in order.
Schedule the family interview via the system; release candidate contact info to the coordinator at this gate. release timing (interview vs. earlier).
The preferred route: the agency logs the decision within 24h of the interview (the aide's text in B24 is the fallback). Escalate + flag if missing. On "hired", update the aide's availability to on-placement.
The aide's two-day check-in reply is stored as a value and checked against the agency's log; silence after two questions waits in a weekly list unless the agency logged the hire, and a monthly count per agency sets interviews against logged hires. The roster re-appearance check: an aide referred to an agency in the past twelve months who appears on its next roster with no hire logged opens an item, with zero texts. Wider questions wait on triggers (ADR-0016).
Turn an agency's bench list into consented Members: dedup against the DB, invite each new person to register (consent + certs + availability), then set the submitting agency's priority. Aide-side of AA-4. Stated creds start matching; proof required before finalizing. priority collisions. v1 path is B40 (invitation, provenance instead of priority).
Watch cert expirations (alert 60/30/14 days), in-service hours (MB-7), and the HHA currency rule; nudge the Member and flag for the operator.
The upload side of vetting docs (B17 is download): accept file → encrypt at rest → record + log. Turns stated creds into verified proof.
Later, behind the same signature port as AA-3's click-to-sign (trigger: more than five MSAs a month, or counsel): send the MSA template (Dropbox Sign / DocuSign) → agency signs → completion webhook → store signed PDF and audit certificate → unblock placement/billing.
When a new Member registers, immediately check them against existing open cases and surface any match (notify the agency and/or the Member).
Aggregate the month's accrued invoice records (B6) into one statement per agency, then charge via Stripe. Replaces per-placement charging.
In-app is the aide's primary channel (ADR-0014). Two paths: push — notify (B19) when a match appears, in the app first and by text if unseen; pull — the Member opens the portal/app and browses. If they browse while not available, prompt to update availability (B32).
One place that changes a Member's availability: self-update (MB-1), prompted (B31), response-derived (B4/B9/B23), and a dormancy timer (active→passive→dormant).
Bill a verified vetting packet without a placement — invoice record → monthly statement (B30). Serves OP-13.
On agency request, find a specific former employee, re-engage (consent B5/outreach B3), and bill $100–$300. Serves OP-14.
Recurring monthly charge for an agency market-intelligence subscription (derived from B18 learning). Serves OP-14.
A Member refers a friend → new Prospect (source=referral) → on successful placement, credit the referrer's incentive. Serves MB-9.
Pluggable per-source adapters (job boards, resume databases, multi-post, ATS) behind one interface — the SourcingSearch / JobAdPublisher ports with a mock provider and no vendor configured in v1 — + CSV bulk import/export. Serves OP-15. Decided 2026-11-09 (ADR-0018): the edges share one small library, not a framework: the shared ingress pipeline with its contract-test kit covers every webhook, and no integration platform carries an aide's handle or an email body.
An aide's free-text question about pay, place, shift or start is answered from the job post by a rule table, with no model; anything else goes to the coordinator's queue with the full conversation. Decided 2026-11-08 (ADR-0017): the model answer waits for its trigger, more than 30% of escalations being logistics questions or more than 50 a week. Serves CC-12.
An aide not on the matched list expresses interest in a job post → same path (rule-table answer for pay, place, shift and start, else the coordinator's queue; a model only later, on its trigger). Serves MB-10.
Added 10/21. Promote four columns (name, phone, ZIP, credential) and capture every other column raw in roster_import_rows, read by nothing (David, 2026-11-10) → dedup by E.164 phone against Members, open invitations from any agency, and the suppression list → write roster_invitations (batch_id, status) → send one agency-branded SMS per row through the consent-gated send path (B5 — STOP honoured on this message too) → on sign-up (PR-4) create the Member with provenance = inviting agency + first-choice window (W days from roster receipt; the matcher puts the introducing agency's cases first and holds other agencies' cases for that aide while the window is open; ADR-0002 Amendment 2) → purge unanswered rows ~90 days after the send, keeping an HMAC of the phone as the no-re-invite key. Serves AA-7 / PR-4. Explorer: simulated SMS, shared seed + delta store.
Where the detail lives
This page is the plain, first-look picture of who uses JobCare and what it does. The engineering detail — where each capability comes from, the full coverage matrix, the open gaps, and the decision history — is kept in docs/requirements/requirements.md so it doesn't clutter the scenarios here. The Flow Atlas holds the sequence diagram for every backend flow (B1–B40). The v1 / later / cut tag on every card comes from requirements.md §2b (ADR-0003).
Where it runs (decided 2026-11-10, ADR-0020). JobCare runs in four cloud accounts in one organisation: management (billing and the policies; it runs nothing), production, non-production and the log archive, each root on a hardware key. Staging, in the non-production account, takes every merge first, runs the nightly drill that may break it, and is reset to the synthetic seed nightly. The demo is kept apart from staging in the same account: it runs the production image, is never drilled, lets runs the demo image built from the same commit as production and binds every outside provider to a mock that answers with simulated responses so nothing real is contacted (2026-11-11), and is reset nightly except the prospect logins David creates, each in a pre-seeded demo agency of the prospect's own (2026-11-10), which persist; that is the one stated exception to "no real person's data in non-production". A pull request gets a client preview pointed at staging, and a full preview when David sets a label; the laptop runs the mock adapters on the seed snapshot; the Flow Explorer moves into the non-production account and is kept as the planning tool. David's merge to main is the production deploy: the same image goes to staging and then production (migration, rolling container, client with one invalidation, then the drill, the smoke and the receipt), and roll back is the previous image and client. Only a run David started can deploy, through a role bound to his id, with main protected on the source host's Team plan. Hashed client files are cached for a year and the page shell never, and a client older than the API's floor shows a reload notice.
How it is watched and recovered (decided 2026-11-11, ADR-0021). Two objectives are measured, a month long: the screens answer from outside at 99.5 percent, and no text is sent after a revocation took effect, zero, proven by a nightly reconciliation against what the texting provider delivered. Alarms run on the cloud's own services by text, by email and as items in the operator queue, which is the page David reads with a 7 a.m. digest and one dashboard; a text unacknowledged thirty minutes reaches the second named owner, whose one action is to call David, and there is no status page and no published uptime. The recovery point stays five minutes and none for consent, with continuous cross-region backup replication and the second region pre-provisioned; inside the region the screens recover in one hour and the STOP path loses nothing, a region loss takes about three hours, rehearsed twice a year, and seven one-page runbooks exist at the tag.
How it is proven (decided 2026-11-11, ADR-0022). There are two kinds of test. Safety tests block a merge: another agency's rows read, a vendor drifted from its real API, a phone number written into a log, a text sent without consent. Correctness tests are the agent's evidence, which David reads first, and never block a merge by their count. Every new or changed test must fail against the code before the change. A pull request runs in two parallel jobs under ten minutes, a merge is the production deploy after staging, and five browser journeys run nightly in staging with none blocking a merge. A story is done only when every acceptance criterion is bound by name to one test, drill, runbook step or dated review, and the stories build refuses a story marked done otherwise.
How the aide is reached (decided 2026-11-11, ADR-0023). The aide holds a text and a web app opened from its link, which can be added to the home screen from day one. There is no push and no native app in version one; each waits on a measured trigger. The link opens one thread for seventy-two hours without a sign-in and asks for the texted code for anything beyond that thread. The screens are English, written so a second language is one more file, and the first aide screen built is join and sign-in. The consent wording, the STOP and HELP lines, the opt-out words, every aide-facing text listed in story B3.2 and the two-segment bilingual roster invitation are in Spanish at launch, written without the four accents the cheap-text alphabet lacks so they cost what English costs. The aide's and the agency's screens meet WCAG 2.1 AA, and each person carries a preferred language, English or Spanish, chosen on the join form (MB-1).
How the work moves (decided 2026-11-13, ADR-0024). Everything lives in one repository on trunk, and main is the only long-lived branch. The review branch is fast-forwarded onto main and then locked under its own name, so the sales demo keeps building from it until the Flow Explorer runs in the non-production account. Main is built as the planning site at plan.jobcareus.com, behind the hosting's password and never public, so the stories page follows every merge. Each story gets one short branch named by its id, rebased and never merged from main, and David squash-merges it with the title "<ID>: sentence". Only one change touching the schema or the contract is in flight at a time. A story is draft, approved or done as declared in its file, and in build or in review as derived from the host by the pipeline's stories build; the planning site shows the declared states only. One next list, docs/stories/NEXT.md, is David's file and says what an agent takes next. A defect found after merge is a fix story whose one criterion is the failing test. A release is the squash commit named in the deploy receipt, the squash titles are the changelog, one tag is ever applied (launch), and a change that must wait carries the held label, which greys the merge button. A two-page conventions file, CLAUDE.md at the root, is what the agent tooling reads first. There is no development branch, no issues or board and no flag service, each waiting on its trigger. The plan is 20 to 22 weeks with David at eight to ten hours a week, a build day being one agent working day with three stories in flight; the first phase is three to four weeks with the first screen at its end, re-estimated after four measured weeks (brief K, 2026-11-13).