ADR-0005: Lazy Case Creation¶
Status: Accepted Date: 2026-03-26 Session: 22
Context¶
A "case" in Curaway represents a patient's journey through the system -- their medical records, conversations, matches, and consent artifacts are all attached to a case. The question is: when should this case record be created in the database?
Early designs created a case at user registration or when the patient first opened the chat interface. This led to a large number of empty cases from users who registered but never engaged, or who opened the chat and navigated away. These empty cases polluted analytics, inflated funnel metrics, and complicated the admin dashboard.
Decision¶
Create a case lazily -- only on the patient's first meaningful interaction. A "meaningful interaction" is defined as either sending the first chat message or uploading the first document.
Rationale¶
- No empty cases. By deferring creation until a real interaction occurs, every case in the database represents a patient who actually engaged. This makes funnel analytics accurate and meaningful.
- Zero-state UX. Before a case exists, the UI shows a clean zero-state: a centered input bar with prompt suggestions (similar to ChatGPT's empty state). This is a better first impression than a dashboard full of empty widgets.
- Simpler lifecycle. A case is guaranteed to have at least one message or document from the moment it exists. Downstream logic (EHR extraction, matching, notifications) does not need to handle the "empty case" edge case.
- Database hygiene. Fewer rows in the
casestable means faster queries, smaller backups, and less noise in Metabase dashboards.
Alternatives Considered¶
| Alternative | Pros | Cons | Verdict |
|---|---|---|---|
| Create on registration | Case always exists; simpler mental model | Massive number of empty cases from users who register but never engage | Rejected |
| Create on page load | Case ready before user types | Creates cases from accidental visits, bot traffic, and users who bounce | Rejected |
| Create on explicit "Start Case" button | Clear user intent signal | Adds friction; one more click before the user can start talking | Rejected |
Consequences¶
- Positive: Database contains only meaningful cases. Analytics reflect real engagement.
- Positive: Clean zero-state UX reduces cognitive load for new patients.
- Negative: The first message or upload has slightly higher latency because it must create the case, the conversation, and process the interaction in one request. This is mitigated by creating the case and conversation in a single database transaction.
- Negative: Code that references
current_casemust handle the null case (no case yet). This requires a guard in the API layer. - Accepted risk: If case creation fails during the first interaction, the patient's message is lost. Mitigated by returning a clear error and prompting retry.