Clients

Part of the Anaya Care Handbook — the source of truth for how the product must behave. When the product needs to change, change this document first, then make the system match it.

What this covers

This page governs clients — the people receiving care. It defines what a client record contains, how a client moves through their lifecycle (Draft, Active, On Hold, Closed), how care providers are assigned to a client's care team, how family representatives and medical professionals are linked to a client, what the medical record holds, and what happens when a client is removed. Every client belongs to exactly one business (agency); nothing about a client is ever visible to another business.

Key terms

• Client — a person receiving care from the agency. Sometimes called a resident.
• Client profile — the client's personal details: name, date of birth, address, language, pets, health baselines, personal-history narrative, and care preferences.
• Client status — where the client is in their lifecycle: Draft, Active, On Hold, or Closed.
• Care team — the agency's own staff assigned to that one client: the client's accountable care managers plus the care providers assigned to them. Membership is always a per-client assignment, never a job title — an admin who holds no assignment on this client is not on their care team. This is the audience for a client's staff notifications. The Care Circle is deliberately excluded (see CL-34).
• Care team assignment — the link between one client and one care provider, with its own status and a priority order.
• Care manager assignment — the link between one client and one accountable care manager, with its own status; eligibility is by permission (manage care reviews), not by role name.
• External care providers — outside organizations involved in the client's care (home-health agencies and pharmacies), stored as contact information only. Not the care team.
• Care Circle — everyone involved in a client's care other than the client themselves (family, existing caregivers, friends). It is captured once at intake and shared identically by the initial assessment, the care proposal, and the client record, so nothing is re-entered as the client moves through onboarding. The client is never a Care Circle member — their own profile represents them.
• Care Circle member — one person in the Care Circle: their name, phone, email, relationship to the client, one or more Care Circle roles, and notes.
• Care Circle role — a hat a member wears, chosen from a fixed multi-select set of six: Signs paperwork, Day-to-day contact, Hands-on support, Handles finances, Lives with client, and Rarely involved. Replaces the old free-text "decision authorities".
• Representative — the family-facing portal login. A Representative is now a thin access grant tied to one Care Circle member — the person's relationship and roles live on the Care Circle, not on the login — and one is provisioned automatically for each member who has an email. Formerly called "Family".
• Responsible party — the one Care Circle member (or the client themselves) designated as the client's decision-maker of record. It is recorded as a pointer to a member (or to the client) that must be set explicitly and is resolved, never invented: an unset or stale pointer resolves to no one rather than defaulting to the first contact. The responsible party authorizes the care plan, is the default recipient of the emailed care proposal, and acts as the data and Anaya Wallet gatekeeper (granting access and approving spending). The client's other family contacts are simply the remaining Care Circle members.
• DNR & Advance-Directive alert — a non-dismissible banner shown at the top of the client profile and care plan when the client has a Do-Not-Resuscitate order or advance directive on file. Care providers must acknowledge it before their first shift.
• 30-day meal plan — a rolling four-week plan of the client's meals, grounded in their dietary preferences and Meal Assessment.
• Medical record — the client's medical history: allergies, diagnoses and conditions, hospitalizations, surgeries, and medical equipment.
• Service information — the type of care the client receives (In-Home Care, Hospice Care, Respite Care, or Placement) and its start/end dates.
• Client reference ID — a short identifier shown for and searchable on each client.
• Care assessments — the six evaluations on the client's record that ground the care plan; detailed on their own page.

How it works

The client record

Every client record holds the person's personal details, address, and language, plus three companion records created automatically with every client: service information, external care providers, and the medical record. The client's timezone is worked out from their address and is the basis for all of the client's scheduling (see Schedules & Shifts). An "advance directive on file" indicator is kept up to date automatically from the documents stored in the client's secure document vault.

The record also carries the six care assessments — Simplified Routine Task Inventory, Routine Task Inventory, Montessori Profile, Allen Cognitive Level, Home Safety, and Meal Assessment. They are the foundation of the client's care plan: who the client is, what they can do on their own, how their mind works, whether their home is safe, and how they eat. Each has its own status (Not Started, Draft, Completed) visible on the client's dashboard.

The full profile is organized into sections: personal information; health information (including the DNR & Advance-Directive alert described below); care and support information (including the 30-day meal plan); personal history and preferences; insurance and financial details; the care team; and document links.

DNR & Advance-Directive alert

When a client has a Do-Not-Resuscitate order or advance directive on file, a non-dismissible alert appears at the top of both the client profile and the care plan. Care providers must acknowledge this alert before their first shift with the client. The alert draws on the same advance-directive information surfaced in Health Monitoring, and is distinct from the automatic "advance directive on file" indicator that is kept in sync from the client's secure document vault.

The 30-day meal plan

The client's care and support information includes a rolling 30-day meal plan — four weeks of planned meals grounded in the client's dietary preferences and Meal Assessment. The day-to-day meal experience itself lives in Meals.

Document links

The profile gathers links to the client's key documents in one place: the secure document vault (Care Lock), discharge notes, the client's assessment history, and the client's incident-report history. These are quick references into records that live elsewhere; the client record does not duplicate them.

Lifecycle

• Draft — the client is being set up. The care team, schedules, and assessments can all be prepared while in Draft.
• Active — care is underway. A client becomes Active automatically the first time a care plan is published for them; staff never set Active by hand.
• On Hold — care is paused. No new care team assignments, schedules, or shifts can be created.
• Closed — care has ended. This is final and keeps the client's history for the record. If the person returns, a new client record is created.

Owners and admins (and any role granted the "change client status" permission, typically care managers) make the manual moves. Every status change records who made it, when, and an optional note.

Creating a client

A client can be created three ways, and all three start in Draft:

1. Manually — staff fill in the profile from scratch.
2. From a care proposal — once a proposal is complete, it can be converted into a client. The client inherits the proposal's information — including its Care Circle, responsible party, and care-decision involvement, carried over without re-entry — and the proposal's Simplified Routine Task Inventory is seeded onto the client already Completed. Every Care Circle member with an email is automatically provisioned portal access (a Representative). The proposal is marked "In Service" and linked to the new client (see Care Proposals).
3. By duplicating an existing client — copies the profile, companion records, assessments, and medications (without attached files) into a fresh record with its own reference ID.

The care team

Staff add the agency's care providers to a client's care team either directly or by accepting a job application for that client (see Job Postings). Care-team membership and shift assignment are separate decisions: acceptance can add the provider to the team and stage the shifts approved from their application, while the later Shift Assignment step performs the live re-check and commits the work. A matching view helps staff choose, ranking providers by distance, rating, skills, declared availability, current commitments, and staged coverage. Team members have a priority order that staff can rearrange. A care provider can only see and work with clients they are actively assigned to.

Beyond the agency's assigned care providers, the broader care team picture spans everyone involved in the client's care: the care manager, the assigned care providers, the primary care provider (PCP), specialists, home-health contacts, the pharmacy, the responsible party, and any additional family contacts. The agency's care providers are the working team described above; the others — PCP, specialists, home health, and pharmacy — are held as contact information (see external care providers and the Communication page), and the responsible party and family contacts are assembled as the client's Care Circle.

The Care Circle, representatives, and medical professionals

A client's Care Circle is the roster of everyone involved in their care other than the client — each member's name, contact details, relationship, and roles. Staff maintain it directly on the client record through the Care Circle editor. When a client is created from a care proposal, the Care Circle carries over from the proposal without re-entry.

Every Care Circle member who has an email address is automatically provisioned portal access — a Representative login tied to that member. The member's relationship and roles stay on the Care Circle; the Representative record is only the access grant. A representative can only see the clients they are actively linked to, and removing a representative deactivates that portal access while the Care Circle member (the person, their relationship, and roles) stays on the client record. Medical professionals are linked to the client the same admin-driven way, separately from the Care Circle.

Family onboarding

When a representative is added, they are brought on board through a guided onboarding flow:

1. Invitation — the representative receives an invitation by email or SMS containing a secure link.
2. Account creation — they create an account with identity and relationship verification, and set up multi-factor authentication (MFA).
3. Guided tutorial — a walkthrough of the portal, covering Care Connect, Care Feed, Care Lock, and Anaya Wallet.
4. Preference settings — they set their notification preferences, their Care Feed face-photo permissions, and their language.
5. Care-plan review and sign-off — they review the care plan and sign off with a digital signature; the care manager is notified.
6. Care Lock setup — they upload initial critical documents to the secure vault.
7. Anaya Wallet setup (future) — they configure a funding method and balance limits.

Removing a client

Removing a client is permanent. It deletes the client and everything connected to them — companion records, assessments, care plans, schedules, shifts, task history, medication logs, health records, reports, and the care team links. Staff can optionally delete the originating care proposal at the same time, or leave it and simply unlink it. Because Closed already preserves history, removal is reserved for genuine clean-up and requires its own permission.

Rules

Implementation status — audited against apps/backend/src/clients, apps/backend/src/users/entities/representative-profile.entity.ts, and packages/shared/src/utils/care-circle.ts on 2026-07-22. ✅ In code · ⚠️ Partial (built, but doesn't fully match the rule) · 🚧 Spec only (not yet built).

• CL-1 — A client can be created in three ways: manually by agency staff, from a completed care proposal, or by duplicating an existing client. All three must start the client in Draft status. (✅ In code)
• CL-2 — Every client must belong to exactly one business. No information about a client may ever be visible to another business. (✅ In code — a global query plugin auto-scopes every client query to the requesting user's business)
• CL-3 — Every new client must automatically receive three companion records: service information (defaulting to In-Home Care when created manually), external care providers, and a medical record. (✅ In code — all three are created on every client; note a rare partial-failure path can still leave service information missing, see Known gaps)
• CL-4 — Every client must carry a short reference ID, and that ID must be unique within the business. (✅ In code — sparse unique index on { business, patientId }; create/duplicate retries on collision)
• CL-5 — A client's status is always exactly one of Draft, Active, On Hold, or Closed, and every status change must record who made it, when, and any note. (✅ In code)
• CL-6 — A client can only become Active automatically, when their first care plan is published. Staff must never be able to set Active manually, and auto-activation only happens from Draft and only when a real person triggered the publish. (✅ In code — the transition map blocks manual Active, and auto-activation only fires from Draft on a user-triggered first publish)
• CL-7 — Manual status changes can only be made by owners, admins, or roles granted the "change client status" permission. Everyone else must be unable to change a client's status. (✅ In code)
• CL-8 — Closed is final. A closed client can never be reopened; re-admission requires a new client record. (✅ In code — Closed has no outgoing transitions in the state machine)
• CL-9 — While a client is On Hold or Closed, no new care team assignments, schedules, shifts, or care proposals can be created for them. Draft clients are exempt so the team can be set up during onboarding. (✅ In code — assignments/schedules/shifts already gated; duplicating a care proposal linked to an On Hold/Closed client is rejected)
• CL-10 — Only users with the Care Provider role can be placed on a care team, and a client can never have more than one assignment per care provider. (✅ In code — role is checked on assignment and a unique client+caregiver index prevents duplicates)
• CL-11 — Care team assignment status changes must be restricted to authorized staff and must follow the assignment lifecycle; arbitrary status edits are not allowed. (✅ In code — only CLIENTS_MANAGE may change status; only ASSIGNED ↔ INACTIVE are allowed; care providers are assigned directly with no invite/accept flow)
• CL-12 — A care provider can only access clients they hold an active care team assignment for. Agency admins can access all of the business's clients. (✅ In code — client list is scoped to ASSIGNED caregiver assignments for Care Providers)
• CL-13 — A representative can only access clients they hold an active representative link for, in every view (detail and lists alike). (✅ In code — client list is scoped to active representative links; detail already rejected unlinked reps)
• CL-14 — A Representative is portal access tied to one Care Circle member: an existing user can only be linked if they already hold the Representative role, and there can never be more than one active link per {client, Care Circle member} pair. (✅ In code — a uniqueness index on the active {client, care-circle member} link prevents double-linking)
• CL-15 — When staff create a new representative or medical professional account, the email and phone number must be unique across the whole platform. If the duplicate belongs to the same business, staff are pointed to "select existing" instead. (✅ In code — email and phone are checked platform-wide, with a "select existing" message for same-business duplicates)
• CL-16 — Removing a representative deactivates only their portal access, not the person: the Care Circle member (their relationship and roles) stays on the client record, and the deactivated link is preserved rather than erased. (✅ In code — removal sets the portal link to inactive; the Care Circle member is untouched)
• CL-17 — The client's timezone must always be derived from their address and must be recalculated whenever the address changes. (✅ In code — timezone is derived from the address on create and recomputed when the address changes)
• CL-18 — The "advance directive on file" indicator must always reflect whether advance-directive documents actually exist in the client's document vault; it is never set by hand. (✅ In code — a document-vault listener keeps hasAdvanceDirective in sync; the retired hasDnrOrder field has been removed)
• CL-19 — Removing a client is a permanent deletion of the client and all connected records, including care team assignments and Representative portal links. It requires the dedicated client-removal permission. (✅ In code — hard-delete cascades include representative_profiles)
• CL-20 — Duplicating a client must copy the profile, companion records, assessments, and medications without attached files, and must produce a fresh reference ID in Draft status. (✅ In code — duplication copies the profile, companion records, assessments, and medications without files, with a new reference ID and Draft status)
• CL-21 — Two staff members changing the same client's status at the same time must never both succeed; the second change is rejected and must be retried. (✅ In code — status writes use the expected current status as an atomic precondition and reject the loser)
• CL-22 — Every view of a client's details or medical record must be recorded in the access audit log. (✅ In code — the detail, medical-record, and medication views carry a PHI-access audit decorator)
• CL-23 — When a client has a Do-Not-Resuscitate order or advance directive on file, a non-dismissible alert must appear at the top of both the client profile and the care plan. (🚧 Spec only)
• CL-24 — Each care provider must acknowledge the DNR & Advance-Directive alert before their first shift with the client, and that acknowledgment must be recorded. (🚧 Spec only)
• CL-25 — The client's care and support information must include a rolling 30-day meal plan grounded in the client's dietary preferences and Meal Assessment. (🚧 Spec only)
• CL-26 — The client profile must gather links to the client's Care Lock vault, discharge notes, assessment history, and incident-report history in one place, as references into records held elsewhere. (🚧 Spec only)
• CL-27 — A newly added representative must be onboarded through a guided flow: a secure invitation by email or SMS, account creation with identity and relationship verification and MFA, a tutorial, preference settings, care-plan review with a digital signature that notifies the care manager, and Care Lock setup. (🚧 Spec only)
• CL-28 — A client's Care Circle is the roster of everyone involved in their care other than the client; the client is never a Care Circle member. Each member carries a name, contact details, a relationship, and one or more roles. (✅ In code — the Care Circle is normalized to strip any client row on every write)
• CL-29 — The responsible party is a pointer to one Care Circle member (or to the client themselves) that must be set explicitly and is resolved, never invented: an unset or stale pointer resolves to no one, and the platform must never default it to the first contact. The responsible party authorizes the care plan and is the default recipient of the emailed care proposal. (✅ In code)
• CL-30 — When a client is created from a care proposal, the Care Circle, responsible party, and care-decision involvement carry over from the proposal without re-entry, and every Care Circle member with an email is automatically provisioned portal access (a Representative). (✅ In code)
• CL-31 — Care Circle roles are a fixed set of six — Signs paperwork, Day-to-day contact, Hands-on support, Handles finances, Lives with client, and Rarely involved — chosen as a multi-select per member; they replace the former free-text decision authorities. (✅ In code)
• CL-32 — Care-team membership and shift assignment are separate records and workflow steps. Adding a provider to the team must not by itself assign any shift. (🚧 Spec only)
• CL-33 — Accepting a client-linked coverage application adds or activates the provider on the care team and stages the approved shifts; final assignment remains governed by Scheduling & Shifts. Returning a previously removed provider reactivates their existing membership rather than creating a second one. (✅ In code)
• CL-34 — A client's care team, wherever it is resolved as a notification audience, is exactly that client's actively-assigned care managers plus their assigned care providers. It is never widened to every management-tier user in the agency, and it never silently includes the Care Circle — representatives are a separate audience that each notification must choose deliberately. (✅ In code — single resolver in CareTeamService, locked by care-team.service.spec.ts)

Who can do what

Decisions needed

1. Should permanent client removal remain available at all, given Closed is the history-preserving end state? Options: keep hard removal behind its permission, restrict it to platform administrators only, or replace it with Closed plus a data-retention policy.
2. What exactly must a care provider acknowledge for the advance-directive alert, and how is "first shift" determined (CL-24)? The product uses vault-synced hasAdvanceDirective only (no separate DNR flag). Options: acknowledge once per client before the very first clock-in, re-acknowledge whenever the directive changes, or acknowledge per shift.
3. Where should the 30-day meal plan live and what generates it (CL-25)? Options: store it on the client record, derive it on demand from the Meal Assessment and dietary preferences, or manage it entirely within Meals and only link to it from the profile.

Follow-on (greenfield)

• Non-dismissible advance-directive alert UI + acknowledge-before-first-shift (CL-23/CL-24).
• Rolling 30-day meal plan on the client record (CL-25).
• Profile hub links to Care Lock, discharge notes, assessment history, and incidents (CL-26).
• Guided family onboarding (CL-27).
• Implementing Caring Touch / Always Fresh / Care Bliss beyond their current placeholders.
• Client Memory undo/hand-edit and care-feed → memory linking (see Client Memory).