Hospital and Surgery Center Developer Guide

OverviewCopy Anchor Link

The Hospital app is a frontend micro-app for facility operations. It provides one app boundary for the Surgery Center and Hospital 50 presets. It is served under /hsp/* and runs within the existing MFA shell.

The app does not own authentication, tenant selection, facility membership, RBAC configuration, or feature-flag administration. The shell supplies identity and effective permissions. The Admin app owns feature flags. The backend remains authoritative for authorization, facility access, and tenant isolation.

The private-document foundation provides U3 APIs, quarantine, revision history, and a typed HTTP consumer for later Lab/insurance work. Uploads default off; selected scanning, retention/deletion policy, D2 deployment approval, and U5 insurance workflows remain pending. Use the document QA guide for its acceptance boundary. The focused U4 Lab plan governs the real-HTTP upload, review, readiness, and OT journey, with automated acceptance tests and manual QA steps. The candidate now has a typed live Lab workqueue, report links, review, and current-source OT gates. See the Lab developer guide and manual QA. The U4 workflow has passed local API and authenticated browser tests in both presets. The final scoped external follow-up completed with no findings. Deployment, manual QA, and D2/D3 acceptance remain open; use the release record for review coverage and limits.

This guide describes the current implementation. The API reference lists endpoint ownership and integration status. The implementation backlog tracks remaining work by phase. The Hospital API contract defines broader planned resource contracts; it is not proof that every endpoint exists.

For remaining implementation, use the workflow and settings gap-closure plan. It links the master and phase plans, maps all 15 routes and setting effects, and names unresolved prerequisites. It does not mark planned workflows as shipped. The forward delivery sequence groups the remaining units into complete Surgery Center journeys before deeper ward operations. Use the backlog delivery order for the short version; settings effects, source-backed dashboard metrics, and real-HTTP QA progress with each delivery.

Inventory source work has a separate ledger implementation plan, API contract, and boundary ADR. They refine gap-closure U9. All six Inventory source units and the U10 case-stock consumer merged through PR 2642. Merge and passing focused tests do not prove deployment or pilot acceptance. The release record retains the explicit Billing-only CI exception from that merge. The Inventory developer guide records all accepted recommendations, foundation safeguards, Unit 2 permission rules, and delivery limits. The ledger contract review records the earlier document review and approved expiry-validation action. It is not a current implementation status report. The case-stock guide describes U10 commands, source-derived readiness, and retry recovery. Use the case-stock QA guide for manual acceptance. Use the release acceptance record for deployment checks, staging QA, named owners, and clinical and Inventory approvals.

ArchitectureCopy Anchor Link

OT opening hours, maintenance blocks, surgeon policy, and scheduling lock/version rules are described in OT Scheduling Settings. Use its manual QA guide for acceptance.

See the workflow and settings audit for all 15 screen routes and the difference between effective settings and planning metadata.

Important paths:

• frontend/apps/hospital/src/App.tsx: route boundary and providers for standalone development.
• frontend/apps/hospital/src/layouts/HospitalLayout.tsx: shell layout, facility switch, context access, and preset navigation.
• frontend/apps/hospital/src/config/presets.ts: Surgery Center and Hospital 50 module lists, labels, and capacity models.
• frontend/apps/hospital/src/services/types.ts: frontend DTOs.
• frontend/apps/hospital/src/services/hospitalApi.ts: single adapter selection point.
• frontend/apps/hospital/src/services/hospitalHttpApi.ts: real HTTP mappings.
• frontend/apps/hospital/src/services/hospitalMockApi.ts: mock workflow behavior.
• frontend/apps/hospital/src/services/hospitalStockApi.ts and stockTypes.ts: typed live case-stock commands and Inventory lookups. Components do not call apiClient directly.
• frontend/apps/hospital/src/services/hospitalQueryKeys.ts: tenant-, facility-, and profile-scoped query keys.
• frontend/apps/hospital/src/shared/hooks/useHospitalQueryScope.ts: derives the active query scope from shell identity.
• backend/domains/clinical: Hospital models, controllers, policies, services, routes, and migrations.

Data and request flowCopy Anchor Link

1. The shell selects an authenticated profile and active facility.
2. Hospital derives tenant, facility, and profile scope from the shell. Components do not accept tenant IDs as authority.
3. React Query keys include that scope. On facility/profile changes, protected Hospital caches are cleared or refetched.
4. The HTTP adapter uses facility-nested routes and maps the backend data envelope and snake-case fields to frontend DTOs.
5. The backend validates the facility against authenticated membership, checks effective RBAC permissions, applies RLS, and emits audit events for protected operations.

The route facility_id is a selector, not authority. Do not add tenant_id to Hospital API requests. RLS and policy checks are both required; frontend permission gates are not a security boundary.

Ownership boundariesCopy Anchor Link

Do not add role/permission management or feature-flag management pages to Hospital. Do not couple Hospital orchestration to deprecated backend modules or IPD Lite gates. Reuse canonical clinical records only when their semantics match the Hospital workflow.

Development configurationCopy Anchor Link

Hospital mock mode is selected only in a development build when VITE_HOSPITAL_MOCK_MODE=true. The Hospital app's dev script sets this mode. Production builds must use the HTTP adapter. The adapter rejects methods that do not yet have a real endpoint; do not create a silent mock fallback for a missing endpoint.

Run from the frontend/ workspace:

pnpm --filter @kulcare/hospital dev
pnpm --filter @kulcare/hospital typecheck
pnpm --filter @kulcare/hospital lint
pnpm --filter @kulcare/hospital test:run
pnpm --filter @kulcare/hospital build

Standalone UI development uses mock mode and does not prove API or RLS behavior. For real API checks, run the authenticated platform stack and use a test tenant, facility, and role with the required permission catalog entries.

Adding or changing a workflowCopy Anchor Link

1. Confirm the API contract, domain owner, permission key, audit event, and RLS classification.
2. Add or update DTOs in services/types.ts.
3. Implement the HTTP mapping in hospitalHttpApi.ts and matching mock behavior in hospitalMockApi.ts when the workflow uses mock development.
4. Keep page access through hospitalApi or the typed hospitalStockApi consumer; do not call apiClient from components.
5. Add query keys with tenant, facility, and profile scope. Invalidate only the affected resource groups after writes.
6. Add loading, empty, forbidden, validation, stale-write, conflict, and server-error states that apply to the workflow.
7. Add adapter tests for request paths, snake-case mapping, envelopes, and errors. Add backend request, policy, audit, and enforced-role RLS tests for backend behavior.
8. Run the manual checks in the QA guide.

TestingCopy Anchor Link

Hospital frontend tests live in frontend/apps/hospital/tests. HTTP adapter tests use mocked @kulcare/api-client; they verify transport behavior but do not prove backend RLS. Component tests use explicit mock mode. Backend Hospital tests live under backend/domains/clinical/test and must test authorization and tenant isolation using the repository's enforced non-bypass RLS test role.

Before merge, run the focused Hospital frontend tests, typecheck, lint, and build. For backend changes, run focused Minitest and RuboCop targets. A migration change must preserve the repository's additive structure.sql rule. Follow the repo instructions for migration ownership and manual QA checklists.