---
description: Ladill Care specialty module architecture and UX standard
globs: config/care_specialty_modules.php,app/Services/Care/SpecialtyModule*.php,app/Http/Controllers/Care/Specialty*.php,resources/views/care/specialty/**,resources/views/care/settings/modules.blade.php
alwaysApply: false
---

# Specialty modules — Care design standard

Full standard: `docs/specialty-module-design-standard.md`.

## Non-negotiables

- Specialty modules are **native Care extensions**, not standalone apps.
- Design **workflow first** (stages, queues, payment checkpoints, completion), then screens.
- Reuse Care engines: Workflow, **Care Queue Engine (in-app)**, Billing, Appointments, Documents, Permissions, Reports.
- Do **not** depend on Ladill Queue for Care or specialty queues (see `docs/care-queue-engine-and-specialty-plan.md`).
- Use **identical primary actions** (Call Next, Start Consultation, Order Test, Prescribe, Generate Invoice, Discharge, …).
- Prefer extending **`Visit`** as the clinical episode unit before inventing a separate Episode model.
- Contribute to one **patient timeline** — do not create parallel charts.
- Prefer **structured clinical data** over free-text-only fields (AI-ready).

## Current reality

Specialty modules use the **shared specialty shell** on the Care Queue Engine (`SpecialtyShellService`, Overview / Visits / History / Billing / Workspace). Stage maps and service catalogs live in `config/care_specialty_shell.php`. Deepen clinical forms per module in Phase 3 — do **not** invent one-off layouts.

## When adding or deepening a module

1. Add/update catalog entry in `config/care_specialty_modules.php` (and department type if needed).
2. Define specialty workflow stages + queue map in docs or config — not only a nav label.
3. Wire through the **shared specialty shell**, not a one-off Blade page.
4. Seed billable services into Billing — never hardcode invoice lines in the specialty UI.
5. Gate with role allowlists + practitioner department assignment (existing `SpecialtyModuleService` patterns); Emergency/Blood Bank stay `default_on_paid_plans`.