# Practice Onboarding Implementation Plan

This tracker converts the full post-registration practice onboarding specification into implementation phases for the existing Laravel CoCM application.

The public Practice Registration Wizard is already implemented. Do not rebuild it unless a small compatibility change is required.

## Current Architecture Found

- [x] Laravel version identified: Laravel Framework 12.64.0.
- [x] Frontend stack identified: Blade templates, Tailwind CSS 4, Alpine.js, Vite.
- [x] Authentication identified: Laravel session auth for web, Sanctum for API tokens.
- [x] MFA support identified: `users.mfa_secret`, `users.mfa_enabled_at`, remember-device flow.
- [x] Current tenant model identified: `Tenant` model with `status`, `onboarding_status`, public signup intake fields, BAA/eSign verification timestamps.
- [x] Current user model identified: `users.tenant_id`, string `role`, string `status`.
- [x] Current roles identified: `super_admin`, `clinic_admin`, `pcp`, `bhcm`, `psychiatrist`, `patient`.
- [x] Permission style identified: Laravel policies and role helper methods, no Spatie permission package.
- [x] Current invitation system identified: `invitations` table with hashed token, expiration, accepted timestamp.
- [x] Current audit system identified: append-only `audit_logs` table with encrypted old/new values.
- [x] Current file storage identified: private local disk at `storage/app/private`, public disk exists but compliance docs must not use it.
- [x] Current PHI gate identified: `EnsureTenantApproved` and `EnsureTenantApprovedWeb`, currently checking tenant status `approved`.
- [x] Existing admin practice review identified: `admin.tenants.show`.
- [x] Existing staff invitation flow identified: `StaffController`, `CreateInvitation`, `InvitationAcceptanceController`.
- [x] Existing admin patient onboarding module identified. This is patient onboarding, not practice onboarding.

## Current Capability Baseline

- [x] Public registration creates a pending tenant/practice.
- [x] Public registration stores structured practice intake.
- [x] Public registration keeps BAA/eSign acknowledgements separate from actual verification.
- [x] SuperAdmin can review public intake.
- [x] SuperAdmin can manually mark BAA executed.
- [x] SuperAdmin can manually mark eSign/compliance verified.
- [x] SuperAdmin approval is blocked until current BAA/eSign verification checks pass.
- [x] PHI access is blocked for unapproved tenants by middleware/model gates.
- [x] Full lifecycle statuses are partially implemented with legacy `approved` compatibility.
- [x] Practice verification is a separate state/action.
- [x] Request-more-information workflow is implemented for SuperAdmin review.
- [x] Registration rejection workflow is implemented for SuperAdmin review.
- [x] Dedicated first Clinic Admin invitation workflow is implemented.
- [x] Pre-activation Clinic Admin onboarding access is implemented.
- [x] Onboarding task engine is implemented.
- [x] Compliance document upload/review workflow is implemented.
- [x] BAA document evidence is stored privately.
- [x] Readiness/blocker engine is implemented for onboarding tasks.
- [x] Final activation is blocked by required onboarding tasks.

## Guiding Business Rule

Keep these states separate:

- Registration does not equal practice verification.
- Practice verification does not equal Clinic Admin account creation.
- Clinic Admin account does not equal compliance approval.
- Compliance approval does not equal practice activation.
- Practice activation does not automatically grant every user access to every PHI resource.

Final PHI access must require:

- active authenticated user
- valid tenant association
- active tenant
- correct role
- correct policy permission
- applicable compliance/access conditions

## Phase 1 - Lifecycle And SuperAdmin Practice Review

Status: Complete.

Goal: make the practice lifecycle explicit and give SuperAdmins proper review actions without activating practices.

- [x] Add tenant lifecycle statuses without breaking existing active tenants.
  - [x] Support target statuses: `pending_review`, `needs_information`, `verified`, `onboarding`, `ready_for_approval`, `active`, `rejected`, `suspended`, `deactivated`.
  - [x] Support `approved` during transition.
  - [x] Update tenant active/compliance helpers.
  - [x] Backfill existing `approved` tenants to the new active-compatible state.
- [x] Add or refine onboarding statuses.
  - [x] Support target statuses: `registration_submitted`, `practice_review`, `clinic_admin_pending`, `onboarding_in_progress`, `compliance_review`, `ready_for_approval`, `completed`.
- [x] Add verification fields to tenants.
  - [x] `verified_at`
  - [x] `verified_by_user_id`
  - [x] Rejection fields for Phase 1.
- [x] Improve SuperAdmin practice review page.
  - [x] Overview/review card.
  - [x] Registration/intake card.
  - [x] Compliance summary.
  - [x] Clinic Admin status placeholder.
  - [x] Onboarding blockers.
  - [x] Audit history.
- [x] Implement SuperAdmin actions.
  - [x] Verify Practice.
  - [x] Request More Information.
  - [x] Reject Registration.
- [x] Add `PracticeInformationRequest` model/table.
  - [x] Category.
  - [x] Message to practice.
  - [x] Internal note.
  - [x] Open/responded/resolved/cancelled status.
- [x] Add Form Requests for Phase 1 actions.
- [x] Add policy authorization for Phase 1 actions.
- [x] Audit all completed Phase 1 actions.
- [x] Add focused tests.
  - [x] Only SuperAdmin can verify.
  - [x] Verification records actor/time.
  - [x] Request more information records request and does not erase intake.
  - [x] Rejection prevents activation.
  - [x] Existing active tenants still work.

## Phase 2 - Clinic Admin Invitation And Account Claim

Status: Core complete. Invitation, claim, revoke, audit, notifications, onboarding-only access, focused tests, and USA phone/date presentation updates are implemented. Invitation resend and revoked/expired notification emails are still deferred.

Goal: create the first Clinic Admin securely after SuperAdmin verification, with onboarding-only access before practice activation.

- [x] Decide whether to extend existing `invitations` or create a dedicated `clinic_admin_invitations` table.
  - [x] Extended/reused existing `invitations` to keep one hashed-token invitation system.
- [x] Add invitation fields/statuses.
  - [x] First name.
  - [x] Last name.
  - [x] Job title.
  - [x] Phone.
  - [x] Status: pending/accepted/expired/revoked.
  - [x] Invited/last-sent/revoked timestamps added.
- [x] Add Invite Clinic Admin action on SuperAdmin practice review.
  - [x] Prefill from registration primary contact.
  - [x] Allow SuperAdmin edits.
  - [x] Enforce role `clinic_admin`.
- [x] Create secure Clinic Admin claim route.
  - [x] Single-use token.
  - [x] Hash token in database.
  - [x] Expiration.
  - [x] Revoked token handling.
  - [x] No raw token logging.
  - [x] Rate limiting.
- [x] Account claim form.
  - [x] Confirm name.
  - [x] Create password.
  - [x] Accept user terms if required. No separate terms acceptance gate exists in the current app.
  - [x] Optional job title/phone correction.
  - [x] Do not allow email or tenant manipulation.
- [x] Create/update `User` safely.
  - [x] No default passwords.
  - [x] Email verified on claim.
  - [x] Role `clinic_admin`.
  - [x] Status `active`.
  - [x] Tenant association.
- [x] Tenant membership decision.
  - [x] For this repo, keep `users.tenant_id` initially unless multi-tenant memberships become necessary.
  - [x] Document limitation and future `tenant_memberships` migration path.
- [x] Redirect accepted Clinic Admin to practice onboarding, not PHI dashboard.
- [x] Add onboarding-only route/middleware access.
- [x] Audit invitation created/revoked/accepted and user created.
  - [ ] Resend audit is deferred until resend is implemented.
- [x] Add notifications.
  - [x] Clinic Admin invited.
  - [x] Invitation accepted.
  - [ ] Invitation revoked/expired notifications are deferred.
- [x] Add focused tests.
  - [x] SuperAdmin can invite.
  - [x] Normal users cannot invite.
  - [x] Token expires.
  - [x] Token is single use.
  - [x] Revoked token fails.
  - [x] Duplicate email handled safely.
  - [x] Accepted Clinic Admin can access onboarding before activation.
  - [x] Accepted Clinic Admin cannot access PHI before activation.

## Phase 3 - Onboarding Task Engine And Clinic Admin Dashboard

Status: Core complete. Persisted onboarding tasks, initialization, Clinic Admin submissions, SuperAdmin review, readiness blockers, and focused tests are implemented. Document-specific agreement tasks remain part of Phase 4.

Goal: represent onboarding progress in backend data, not hardcoded frontend checks.

- [x] Create `onboarding_tasks` table/model.
  - [x] `tenant_id`
  - [x] `task_key`
  - [x] `category`
  - [x] `title`
  - [x] `description`
  - [x] `status`
  - [x] `is_required`
  - [x] `is_blocking`
  - [x] `sort_order`
  - [x] `assigned_role`
  - [x] `due_at`
  - [x] `completed_at`
  - [x] `completed_by_user_id`
  - [x] `reviewed_at`
  - [x] `reviewed_by_user_id`
  - [x] `rejection_reason`
  - [x] `metadata`
- [x] Create task initialization service.
  - [x] Practice verification.
  - [x] Clinic Admin setup.
  - [x] BAA execution.
  - [ ] Service agreement if required. Deferred to Phase 4 document requirement configuration.
  - [x] Compliance documents.
  - [x] Practice profile.
  - [x] Locations.
  - [x] Clinical team.
  - [x] Psychiatric consultant conditional task.
  - [x] EHR integration conditional task.
  - [x] Billing setup if required.
  - [x] Patient consent configuration.
  - [x] Final review.
- [x] Create Clinic Admin onboarding dashboard.
  - [x] Route: `/practice/onboarding`.
  - [x] Progress percentage.
  - [x] Action Required, Under Review, Completed, Rejected, Not Applicable, Locked states.
  - [x] Responsive and accessible cards.
- [x] Create task update/review service.
- [x] Add task policy and route protection.
- [x] Audit task submission/review.
  - [ ] Reopening is deferred until task-specific forms exist.
- [x] Add focused tests.
  - [x] Conditional tasks generated from intake.
  - [x] Progress calculated correctly.
  - [x] Clinic Admin cannot access another tenant onboarding.
  - [x] Required blocking tasks block readiness.

## Phase 4 - Compliance Documents And BAA Workflow

Status: Core complete. Required document configuration, private PDF upload, protected downloads, SuperAdmin verification/rejection, BAA evidence, compliance timestamp updates, e-sign provider interface, and focused tests are implemented. SuperAdmin-managed custom requirement toggles and real e-sign vendor integration remain future work.

Goal: store real document evidence privately, with Clinic Admin upload and SuperAdmin review.

- [x] Create configurable document requirements.
  - [x] Business Associate Agreement.
  - [x] Master Services Agreement / Services Agreement.
  - [x] Security Addendum.
  - [x] Data Use / Data Processing Agreement if applicable.
  - [x] Implementation Agreement / SOW if applicable.
  - [x] Billing Services Agreement if applicable.
  - [x] EHR Integration Authorization if applicable.
  - [x] Organization Attestation.
  - [x] Other Compliance Document.
- [x] Create `compliance_documents` table/model.
  - [x] `tenant_id`
  - [x] `document_type`
  - [x] `document_name`
  - [x] `version`
  - [x] `status`
  - [x] `disk`
  - [x] `storage_path`
  - [x] `original_filename`
  - [x] `mime_type`
  - [x] `file_size`
  - [x] `checksum`
  - [x] `uploaded_by_user_id`
  - [x] `uploaded_at`
  - [x] `effective_date`
  - [x] `expires_at`
  - [x] `signed_at`
  - [x] `signed_by_name`
  - [x] `signed_by_title`
  - [x] `reviewed_by_user_id`
  - [x] `reviewed_at`
  - [x] `rejection_reason`
  - [x] `superseded_by_document_id`
- [x] Use private storage only.
- [x] Validate uploads.
  - [x] PDF preferred.
  - [x] Size limit.
  - [x] MIME and extension validation.
  - [x] Checksum.
  - [x] Unique generated storage path.
- [x] Add protected download controller.
  - [x] No raw storage paths exposed.
  - [x] Policy checks.
  - [x] Tenant isolation.
- [x] Build Clinic Admin document UI.
  - [x] Required document cards.
  - [x] Upload signed document.
  - [x] Show under-review/rejected/verified states.
  - [x] Show rejection reason.
- [x] Build SuperAdmin document review UI.
  - [x] Document detail.
  - [x] Download.
  - [x] Verify.
  - [x] Reject with required reason.
  - [x] Request replacement.
  - [x] Previous versions.
- [x] Treat BAA as real document evidence.
  - [x] BAA required task.
  - [x] Signed copy upload.
  - [x] Signer name/title/date.
  - [x] SuperAdmin verification updates BAA verification fields only after review.
- [x] Add signature provider abstraction for future e-sign vendor.
  - [x] Interface only initially.
  - [x] No fake e-sign workflow.
- [x] Audit document uploaded/replaced/submitted/verified/rejected.
- [x] Add focused tests.
  - [x] Authorized upload succeeds.
  - [x] Invalid MIME fails.
  - [x] Oversized upload fails.
  - [x] Document stored privately.
  - [x] Practice A cannot download Practice B document.
  - [x] Rejection requires reason.
  - [x] Verification records reviewer.
  - [x] Cannot activate without verified BAA when required.

## Phase 5 - Practice Setup, Team, Integration, Billing, Consent Configuration

Status: Core complete, with dedicated setup-only practice roles, USA phone/date formatting, and organized onboarding/admin surfaces added.

Goal: finish onboarding modules needed before readiness.

- [x] Practice profile editing.
  - [x] Allow safe edits to registration data.
  - [x] Critical changes reopen the task for SuperAdmin review.
  - [x] Audit changes.
- [x] Practice locations setup.
- [x] Clinical team setup.
  - [x] Clinic Administrator.
  - [x] Treating / Billing Practitioner.
  - [x] Behavioral Health Care Manager.
  - [x] Psychiatric Consultant.
  - [x] Billing Staff contact path through billing configuration.
  - [x] Practice Manager contact path through primary contact/profile configuration.
  - [x] Dedicated Billing Staff / Practice Manager / Clinical Support login roles.
    - [x] Setup-only web access to practice onboarding.
    - [x] PHI/admin workspace routes blocked for setup-only roles.
    - [x] Role-scoped onboarding form submission permissions.
- [x] Staff invitation extensions.
  - [x] Clinic Admin can invite permitted roles.
  - [x] Clinic Admin cannot invite SuperAdmin or platform roles.
  - [x] Pre-activation users can claim setup accounts but not access PHI routes.
- [x] Provider profile fields where required.
  - [x] NPI and credentials for practitioners.
  - [x] BHCM caseload settings where applicable.
  - [x] Psychiatric consultant internal/external and required identity fields.
- [x] EHR/integration setup task.
  - [x] Required only when intake says yes/not sure.
  - [x] No credential collection in unsafe forms.
- [x] Billing configuration task if enabled.
- [x] Patient consent configuration task.
  - [x] Verbal/written/e-sign policy.
  - [x] Cost-sharing acknowledgement setting.
  - [x] Psychiatric consultation authorization setting.
  - [x] Keep practice agreement, user agreement, and patient consent separate.
- [x] USA formatting and onboarding UI organization pass.
  - [x] USA phone masking for registration, invitations, and onboarding setup inputs.
  - [x] USA date/time display on onboarding/admin/invitation surfaces touched by practice onboarding.
  - [x] Organized onboarding options into profile, locations, team, configuration, documents, and tasks.
  - [x] Applied a stronger scoped glass/glow/gradient theme to onboarding, public onboarding intake, SuperAdmin, and authenticated admin surfaces.
  - [x] Left the current `/login` page unchanged.
  - [x] Added separate modern login preview route at `/login-modern`.
- [x] Add focused tests for team/task/tenant isolation.

## Phase 6 - Readiness Engine And Activation

Goal: centralize activation blockers and move practices to active only when all blocking requirements are complete.

- [ ] Create `PracticeActivationService`.
  - [ ] `blockers(Tenant $tenant)`.
  - [ ] `canActivate(Tenant $tenant)`.
- [ ] Centralize blockers.
  - [ ] Practice not verified.
  - [ ] Clinic Admin invitation not accepted.
  - [ ] BAA not verified.
  - [ ] Required compliance document missing.
  - [ ] Required onboarding task incomplete.
  - [ ] Clinical team incomplete.
  - [ ] Psychiatric consultant missing.
  - [ ] Required integration unresolved.
  - [ ] Critical compliance document rejected.
- [ ] Mark ready for approval.
  - [ ] `tenant.status = ready_for_approval`.
  - [ ] `tenant.onboarding_status = ready_for_approval`.
  - [ ] Notify SuperAdmin.
  - [ ] Do not auto-activate.
- [ ] Implement final activation action.
  - [ ] Confirmation modal.
  - [ ] Activation notes.
  - [ ] Database transaction.
  - [ ] `approved_at`, `approved_by_user_id`.
  - [ ] `activated_at`, `activated_by_user_id`.
  - [ ] Status moves to active/completed.
  - [ ] Audit log.
  - [ ] Activation notification.
- [ ] Add focused tests.
  - [ ] Cannot activate with blockers.
  - [ ] Ready tenant can activate.
  - [ ] Only SuperAdmin can activate.
  - [ ] Activation recorded correctly.

## Phase 7 - PHI Access, Audit, Notifications, Hardening

Goal: finish security, notifications, route separation, and regression coverage.

- [ ] Update PHI route gating for new lifecycle.
  - [ ] Active tenant status recognized.
  - [ ] Suspended/deactivated tenants blocked.
  - [ ] Pre-activation onboarding routes allowed.
  - [ ] PHI routes remain blocked before activation.
- [ ] Review all tenant-owned policies for IDOR prevention.
- [ ] Add or improve route groups.
  - [ ] `/practice/onboarding/*` for pre-activation onboarding.
  - [ ] Clinical/PHI routes require active tenant and role policy.
- [ ] Extend audit logging coverage.
  - [ ] Practice verified.
  - [ ] Information requested.
  - [ ] Registration rejected.
  - [ ] Clinic Admin invited/resent/revoked/accepted.
  - [ ] Role assigned.
  - [ ] Document lifecycle events.
  - [ ] Task lifecycle events.
  - [ ] Ready for approval.
  - [ ] Activated/suspended/deactivated.
- [ ] Notifications.
  - [ ] Additional information required.
  - [ ] Registration rejected.
  - [ ] Practice verified.
  - [ ] Clinic Admin invitation/reminder/accepted.
  - [ ] Document required/submitted/rejected/verified.
  - [ ] Onboarding action required.
  - [ ] Practice ready for activation.
  - [ ] Practice activated.
- [ ] Queue readiness.
  - [ ] Use queued notifications where project infrastructure supports it.
- [ ] Comprehensive test pass.
  - [ ] Feature tests.
  - [ ] Tenant isolation tests.
  - [ ] PHI access tests.
  - [ ] Full suite.

## Implementation Rules For Future Parts

- [ ] Update this file after each completed task.
- [ ] Keep each implementation part small enough to test.
- [ ] Run focused tests after each phase.
- [ ] Run the full suite after schema/lifecycle/security changes.
- [ ] Do not store raw invitation tokens.
- [ ] Do not store compliance documents in public storage.
- [ ] Do not include PHI in emails, URLs, logs, or analytics.
- [ ] Do not grant PHI access from registration, verification, or Clinic Admin account creation alone.
- [ ] Do not remove or weaken existing tenant isolation.

## Suggested Next Work Item

Continue with Phase 6:

1. Finish `PracticeActivationService` as the single activation blocker source.
2. Add ready-for-approval transition and SuperAdmin activation confirmation.
3. Add focused activation/blocker tests.