TestOrder vs TestEvent

TL;DR

• TestOrders are mutable and TestEvents are immutable.
• TestEvents are reported to ReportStream and TestOrders are not.
• They are cyclically referenced, such that TestOrder has a referenced TestEvent and TestEvent has a referenced TestOrder.
• They contain a good deal of duplicate information, including patient, organization, facility, device, results, and correction status. See BaseTestInfo for a full list.
• For corrections and mutations, the original TestOrder is altered but a new TestEvent is created.
• Test results used to be stored as a column on both TestOrder and TestEvent. Nowadays, there's a separate Result table that includes references to both the TestEvent and TestOrder, as well as the actual result and disease information.
• A TestOrder gets created as soon as a patient is added to the queue. The TestEvent is only created once the queue item is submitted.

A history lesson

At the dawn of time (also known as late 2020) SimpleReport needed a data schema.

This schema had many purposes. It had to be able to send data to public health departments through ReportStream, but it also had to store internal SimpleReport data so that users could view their historic test records. It needed to link tests to specific facilities and organizations, but also to providers who were ordering the tests. There was also the concept of mutability - records that had already been sent to ReportStream couldn't be edited once they hit the public health departments, but within SimpleReport users needed to be able to edit or update their results. What's an engineering team to do?

In this case, they created both a TestOrder and a TestEvent. The TestOrder was pretty literal - it meant that a health care provider had ordered a test, the same way your doctor might order an X-ray. The order had information about the patient, the ordering provider, the facility that the test was order to, when it was ordered, etc. This order was created as soon as you put someone onto the queue within SimpleReport, and given a status of PENDING.

A TestEvent meant that a testing event had finished, and needed to be reported to the public health department. Once created, these records were immediately passed on and reported, so they couldn't be edited after creation.

Initially, the intention was to have TestOrder reference TestEvent as a kind of parent-child relationship. The TestOrder would know about the TestEvent but the Event would remain blissfully unaware of its counterpart. This changed with test corrections, when it was necessary for both TestOrder to know about TestEvent and TestEvent to know about TestOrder. During a correction, Events would be orphaned by their parent Order, so a reference was needed to link the two together. This did have the unfortunate side effect of creating a cycle between TestOrder and TestEvent, to the later frustration of the devs trying to serialize the database for audit logging. But I digress.

Today, TestOrders are still created as soon as a patient is put onto the queue. They can have three potential states - PENDING, COMPLETED, or CANCELLED. Only COMPLETED orders should have an associated TestEvent. The TestEvent is created when the user submits a test (calling the addTestResult mutation).