JobCare. Flow Explorer HomePost a caseOpen postsOperatorCandidate DBSystem MapFlow AtlasStoriesDecisions
JobCare. Flow Atlas · Sequence Diagrams

Requirements alignment · companion to the System Map

Every flow the system runs — including the ones with no screen

The sequence diagrams behind the actor map. UI-triggered flows start from something a person clicks; backend-only flows run on their own — email intake, matching, outreach, consent, billing, check-ins. Each names the exact service boundaries production must build, since almost none of these run for real in the prototype.

1 end-to-end revenue flow 40 component flows (B1–B40) diagrams in Mermaid
UI-triggered starts from a click in a portal
Backend-only runs with no screen
diagrams render on a constant-light panel so they read in either theme
What the 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.

§4.3.1Post case → auto-blast → proceed → docs → interview → decision → billingspans UI + backend
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)
LL144 posture is stronger now: the system contacts every internal match (no auto-reject) and the agency's coordinator decides — ranking stays decision-support, not an automated employment decision, with no JobCare human in the matching loop. 🔴 the match leg still depends on the disputed Indeed/myCNAjobs integrations (see B2).
B1Email intake & AI parsebackend-only
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)
Prototype: a 700 ms timeout around a regex keyword extractor; no inbound mailbox. v1: the paste box only — one server-side structured-output call. The Postmark inbound mailbox is later.
B2Matching engine (2-stage + external merge)backend-only
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)
Decided 2026-10-22 (ADR-0005): the pool is searched first; external search is a port with no provider configured in v1 (a mock provider for the demo and tests), offered when matches are few or on request. 🔴 Reviewer flag (resolved by that decision): no job board offers a candidate-search API for independent recruiters — the biggest open question (tech review). 🔴 Discuss (8/24): a strict deterministic stage-1 is likely too restrictive — move to graded/tolerant matching (adjacent certs, nearby ZIPs) so good candidates aren't filtered out.
B3Outreach orchestration (send)backend-only
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
Updated 8/19. Internal matches get an automatic availability blast using the agency's template under standing consent; external candidates are contacted only when the coordinator requests it, carrying the /join link (B12). Prototype "Send outreach now" is a no-op. Open question: how often the same aide may be re-contacted (frequency cap).
B4Inbound reply & consent updatebackend-only
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
TCPA-critical. Same shape drives dormant re-engagement (dormant → YES → active). A YES is an availability answer only; texting consent is captured at sign-up (B5) and never inferred from a reply (ADR-0004). STOP is honored before anything else. Updated 8/24: free-text is correlated to its existing thread before routing; replies update availability (B32).
B5Consent ledger & TCPA enforcementbackend-only · cross-cutting
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"
Two consent concepts to reconcile: TCPA texting opt-in (here) vs. v1's referral-disclosure consent (click-through vs signed PDF). Both must be modeled. Penalty exposure: $500–$1,500 per text.
B12External candidate → JobCare signup conversionbackend-only
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)
The database-growth mechanism. If the candidate ignores the link, JobCare has still made one permissible contact; continued outreach requires them to be consented in the DB. 🔴 Updated 8/24: every step must stay strictly within the source platform's terms of service — outreach only through their sanctioned channel, no scraping — or we risk being removed from Indeed/myCNAjobs.
B6Invoice record on hire (accrual)backend-only
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)
Updated 8/24 — monthly billing. A hire creates an accrued invoice record, not an immediate charge; B30 rolls the month's records into one statement and charges via Stripe. Tiers: Basic $500–800 · Vetted $1.5–2.5k · Premium $3–5k · Retention +$500. Pricing unresolved — founder's instinct was $200/placement; carried to the tech/commercial review.
B7Payment settlementbackend-only
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)
Updated 8/24: settles the monthly statement (B30), not per-placement invoices. Prototype: markPaid flips seeded invoices; no Stripe. Optional QuickBooks GL sync (v1) is a separate downstream job.
B8Aging invoice remindersbackend-only · scheduled
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
Updated 8/24: reminders are against the monthly statement (B30). Aging report by provider (v1) is the read model over the same data.
B9Post-placement check-ins (billing source-of-truth)backend-only · scheduled
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)
Answers David's open question: how do we know when an aide leaves, with no access to agency systems? The aide's own reply is the source of truth for retention billing (B10) and the fee-leakage defenses. Updated 8/24: handles no-reply (retry → escalate) and non-YES/NO replies, and updates availability on the answer.
B10Retention-bonus invoice @ 90 daysbackend-only · scheduled
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
Depends entirely on B9 retention confirmation being trustworthy.
B11Early-termination — replacement credit (not refund)backend-only
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
Open decision (v1 "biggest liability"): guarantee window 14 vs 30 days. Must be in the MSA. 🔴 Updated 8/24: classify by expected term — post-op placements are often short-term, so a short-term ending shouldn't trigger the guarantee. How to classify short vs. long is an open question.
B16Auth & role provisioningbackend-only
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)
Prototype: click-to-enter demo user, no credentials. MFA required for agency admins and operators.
B17Secure vetting-file accessbackend-only
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)
Every access logged; access requires 2FA. JobCare never stores SSNs, dates of birth or bank details (ADR-0004).
B13–15Cross-cutting archives: events, conversations, cost logbackend-only · everywhere
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
Prototype gap: events are seed-only — no user action emits one, despite the "permanent audit log" claim. Conflict to resolve: "archive everything forever" (chat) vs. "minimal PII / retention limits" (v1) — no retention schedule defined anywhere.
B18Agency preference learning (batch)backend-only · scheduled
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
The LL144-defensible alternative to ML ranking. Agencies can inspect and adjust their own weights.
B19Notification fan-outbackend-only
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
v1: coordinators get a per-event email plus the in-app bell; no SMS to coordinators (CC-12). Prototype: the header bell is decorative. "Notify before login" is explicit in the chat (agency shouldn't have to sit in the app).
B20Partner API + webhooks (Phase 5)backend-only
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
Reuses the same intake+match pipeline as the UI path; adds API-key auth, rate limiting, abuse monitoring.

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.

B21Document & credential request (delta + agency application)backend-only
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
Deferred vetting, made concrete. Only the gaps are requested — the packet travels with the aide, so repeat placements skip what is already verified. All communication via the system.
B22Interview scheduling + contact-info releasebackend-only
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)
🔴 Open question: contact info is released at interview-scheduling here — releasing earlier helps agencies but increases bypass/fee-leakage risk. Scheduling stays in the system even though the coordinator now has the candidate's number.
B23Hiring-decision 24h SLAbackend-only · scheduled
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
Mandatory. The preferred route is the agency logging the outcome within 24h; if it's missing, the fallback is asking the aide directly (B24). A missing decision is itself a suspicion signal. On "hired", the aide's availability flips to on-placement (B32).
B24Case integrity monitoring + post-interview candidate check-inbackend-only
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
The fee-leakage defense, operationalized. The aide's own answer — not the agency's word — is the source of truth for whether a placement happened. Mirrors the retention-check-in mechanism (B9).

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.

B25Agency bench → Prospect onboarding & consentbackend-only
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
Added 8/23. Bench listings are Prospects — they have a relationship with the agency, not JobCare, so they must register to give consent + certs + availability (reuses B4 consent and the /join conversion of B12). Stated creds start matching; proof is required before finalizing (B27). 🔴 Open question: priority collisions — same person from multiple agencies, or already in our system (with another agency's priority, or none). Related: AA-4 (agency side).

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.

B26Credential & compliance monitoringbackend-only · scheduled
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
Added 8/24. Covers MB-1 expiration alerts and MB-7 in-service hours (HHA 12/yr, PCA 6/yr) plus the HHA "≥16 hrs in 2 years" currency rule — so a lapsing credential is caught before it blocks a placement.
B27Secure document uploadbackend-only
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)
Added 8/24. The upload side of vetting docs (B17 is the download/signed-URL side). An upload lands as under review; an operator verifies it (OP-2). That is what turns a Prospect's stated credentials into verified proof — required before a match is finalized.
B28MSA e-signaturebackend-only
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)
Added 8/24. AO-3/AA-3 previously had no flow. Includes the 12-month long-tail clause and replacement-not-refund policy; placement/billing is blocked until this completes.
B29New-Member match-on-signupbackend-only
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
Added 8/24. A fresh registration shouldn't sit idle — check it against open cases immediately and surface any hit. Turns supply growth into placements faster.
B30Monthly billing & statementbackend-only · scheduled
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)
Added 8/24. Replaces immediate per-placement charging: hires accrue invoice records (B6), and one monthly statement per agency is charged. Open question: confirm cadence + statement format.
B31Member views & responds to matches (push + pull)UI + backend
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
Added 8/24. Two ways a Member reaches matches — push (we notify) and pull (they open the app). If they browse while not available, prompt them to fix that (availability drives who we contact).
B32Availability-status lifecyclebackend-only · cross-cutting
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
Added 8/24. v1 states are active, passive, dormant and on placement; STOP is recorded in the consent ledger and the send gate (B5), not here. Availability is the single most important field for outreach eligibility, so every path that changes it lives here: self-service, prompted, response-derived, and the dormancy timer. Keeps CC-3 "who's available" trustworthy.

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.

B33Standalone vetting-packet feebackend-only
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)
Added 8/26 (gap #17). Pure-margin revenue — the packet is billable even when the agency sourced the candidate elsewhere. Serves OP-13.
B34Reactivation — locate & reconnect a former employeebackend-only
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)
Added 8/26 (gap #18). An optional per-request service. Serves OP-14; reuses consent (B5) + outreach (B3).
B35Market-intel subscription billingbackend-only · scheduled
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)
Added 8/26 (gap #18). Recurring revenue from the proprietary data moat. Serves OP-14.
B36Aide-referral intake & incentivebackend-only
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
Added 8/26 (gap #49). The highest-quality/lowest-cost supply channel. Serves MB-9; a referred friend is just a Prospect with attribution.
B37Connector framework + CSV import/exportbackend-only
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
Added 8/26 (gaps #51–53). Pluggable adapters (incl. multi-post distributors + ATS piggyback) behind one interface + CSV bulk import/export. Serves OP-15. Each adapter must stay within its source's ToS (see B12).

Flows added 2026-08-27

B38–B39 cover the AI-agent question handling and non-matched interest paths.

B38AI-agent question handlingbackend-only
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
Added 8/27. Keeps easy questions off the coordinator's plate; escalates the rest with context. Serves CC-12. Deterministic seam now; a real Claude call slots in behind the same interface.
B39Non-matched interest intakebackend-only
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
Added 8/27. An aide the match didn't surface can still raise their hand — same handling as any reply. Serves MB-10.

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.

B40Roster import → invitation → sign-upUI-triggered
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
Added 10/21 (ADR-0002 Amendment 1, pool-model resolution). Exactly one message per invitation, STOP honoured even on that one; the aide enters the pool only on sign-up, consenting to JobCare directly. The inviting agency gets provenance, not exclusivity. Replaces the "CSV bulk import" half of gap #51. Serves AA-7 / PR-4. Open for G5: whether the invitation text is informational or marketing (prior express written consent) — the template, the TCR opt-in description and the agency's attestation decide.
Next: the Tech-stack review — the ~14 SOW-v2 technology decisions, each with a recommendation + alternative, absorbing every 🔴 flag raised here (chiefly the Indeed/myCNAjobs integration reality behind B2).