In a nutshell, we want what’s recorded in the system to match the real world. We know this is impossible (delays, mistakes, changes) but are getting as close as we can. The promise is that if what’s in the system matches the real world as closely as possible, costs go down, customer satisfaction goes up, & we are able to scale further faster.

Here’s how it works.

Scenarios

We’ll take addresses as our example. Addresses are useful for sending correspondence, calculating taxes, determining regulations, & targeting marketing. Addresses, though, change.

Simplest—we’ll just store the address in the database. When the address changes, we’ll change what’s in the database. Finito.

Not quite. The customer calls and says, “Why did you charge me California sales tax for this order? I don’t live in California. 🤬” We look in the database & there it is, a California address. “I just moved you numbskulls. The order was sent to me when I was in Colorado.”

We’re terribly sorry for the mistake. Here’s a voucher for an ice cream cone.

Not a good experience for the customer. Not a good experience for us.

Dated data—we choose to remember the history of all the addresses & tag them with their date. This is more complicated. Now the customer service screens have to display a list of addresses instead of just one. The database will be bigger because we don’t throw addresses away. The code will be more complicated because we can no longer say, “Here’s a customer. What’s their address?” we have to say, “Here’s a customer. What’s their address on this date?”

Yes, it’s more complicated, but in return we get to answer our irate customer’s question. “Our records show that you placed the order on June 15 & you moved on June 1.” Oh.

Okay, so date-tagged data is better for us at the cost of a bit more complexity.

However… What happens when a customer says, “Oh, by the way, I moved 2 months ago.”? What date do we use for the tag? Today? Then we won’t know that we need to recalculate 2 months’ worth of statements. Two months ago? Then we won’t be able to explain (to the customer, tax authorities, whoever) why we did what we did.

The fundamental, inescapable problem? What is in the system is a flawed reflection of what is going on in reality. We want what is in the system to be as close as possible to reality, but we also need to acknowledge that consistency between the system & reality will only ever be approached, not achieved. The system will record changes in reality eventually, but by then we may have made decisions that need to be undone.

Sound difficult? Only a little more than what we’ve done already.

Double-dated data—we tag each bit of business data with 2 dates:

• The date on which the data changed out in the real world, the effective date.

• The date on which the system found out about the change, the posting date.

This is the simple case where effective & posting dates match.

(These 2 dates are why we call such systems “bi-temporal”. We have 2 timelines. One is the timeline of when things actually happened, the other the timeline of when we found out about it. The purpose of the 2 dates is to make sure that our system is eventually consistent with reality.)

Another way to look at the example above is to show the timelines explicitly.

And Now…

Using effective & posting dates together we can record all the strange twists & turns of feeding data into a system.

“I forgot to tell you that I moved last year.”

“You got last year’s address change wrong.”

“I’m going to move next year.”

And this is the magic one, the nightmare scenario that just can’t be automatically handled otherwise.

“You got last year’s address change wrong. I actually moved 2 years ago.”

To accurately process this scenario we need to undo 2 years’ worth of processing, redo those years with the correct address, the continue from there. Without both dates we’re throwing the corrections into an account called “Manual Corrections” & praying those corrections won’t cause problems in the future (praying in vain, as it turns out).

Conclusion

The goal of our design is to provide eventual business consistency, for what’s recorded in the system to match what’s happening in the real world as well as possible at a reasonable cost. Since perfect consistency is impossible:

• We save everything we learn.

• We track when changes occurred in reality.

• We track when we found out about those changes in the system.

We invest additional programming complexity so we can:

• Reduce costs (fewer complaints, faster resolution).

• Reduce mistakes.

• Improve compliance.

That’s the tradeoff. That’s what we’re doing we say we are bi-temporal. GeekSpeak for “better business”.

I’d like to thank Massimo Arnoldi & the Lifeware gang for teaching me bi-temporality, teaching me how to effectively visualize the two timelines, & using bi-temporality to provide outstanding customer service to millions of insurance customers for decades.

Appendix: The Analogy

Bi-temporal data has been around since the early 1990’s, based on the pioneering work of Richard Snodgrass. Part of the reason it hasn’t taken off is because of the additional complexity it imposes on programmers. However, I think part of the reason it hasn’t become more popular, given the benefits it brings, is just the name. Hence my proposed rebranding to “eventual business consistency”.

Unfortunately, that name is itself a geeky analogy. If you already understand “eventual consistency”, the analogy makes immediate sense. If not, probably not so much. At the risk of “explaining the joke” (which never works, right?), here is the analogy.

Say we have a critically important database. We store the data on 2 machines so if one machine crashes we still have access to our data.

Say the network between the 2 machines is flaky (protip: it is). When we write data to one machine & the network is down we can either:

• Wait for the network to come back, which imposes unpredictable delays. If the data absolutely, positively have to be consistent between the 2 machines we may be willing to pay this cost.

• Write the data to one machine now & catch up later. If we absolutely, positively need to be able to write data at all times but it’s okay if the data is a little out of sync, this is an acceptable tradeoff. We call this scenario “eventual consistency”.

It’s this latter, “catch up later”, strategy that we draw our analogy from. Just as the 2 databases are consistent, but only eventually, our system data matches reality, but only eventually. We acknowledge that the system & reality are a little out of whack but we’re transparent about inconsistencies & fix them as well as possible as soon as possible.

Watch designers speak in terms of “complications” instead of “features”. I love this framing because it simultaneously reminds everyone of both costs & benefits.

So far we have discussed:

1. We want the flexibility of human processing with the scale & economy of automated processing.

2. So we save all data needed to recreate the history of a contract.

3. But the real world out there & the ideal world of the system diverge.

4. So we tag all data with both the date on which data became true in the real world & the date on which the system learned about that data (bi-temporality).

Now we come to the next complication: reproduction. We would like to be able to re-run the entire history of a contract from inception to the present moment & get exactly the same results as those we currently have stored (the actual differences will be interesting).

“That fee is outrageous! I’ll only pay half that.” “But that was 5 years ago!” “I don’t care.” Imagine being able to retroactively change the fee, re-run the entire 5 years worth of transactions, & confidently seeing how the balances have changed.

To replay history we must record it.

Accounts & Transactions

Therefore, record monetary flows as transactions between accounts. Bi-temporally stamp these transactions. Implement business logic by reading account balances & posting new transactions.

There is a whole Tao Te Ching 道德經 interpretation of double entry bookkeeping which I’m not going to describe here because I’m no initiate. Feel free to explore.

What accounts do you need? That’s a matter of style, judgement, & iteration. In general, have an account any time a balance is interesting to someone. “How much have I paid in premiums?” Account. “How much risk did we re-insure?” Account. “What is the current street address?” Not an account (but maybe it should be—try it some time).

Implementation: Structure

SubStack is responding differently to indenting than it has before for me. I’m afraid you’ll have to fill in the leading whitespace yourself until I get it figured out.

Here is the basic test we’d like to pass:

monday = 1
tuesday = 2
wednesday = 3
thursday = 4
source = Account()
destination = Account()
Transaction.post(source, destination, 100, tuesdayAsOfTuesday)
mondayAsOfMonday = Perspective(effective=monday, posting=monday)
assert source.balance(mondayAsOfMonday) == 0
tuesdayAsOfTuesday = Perspective(tuesday, tuesday)
assert source.balance(tuesdayAsOfTuesday) == -100
tuesdayAsOfThursday = Perspective(thursday, tuesday)
assert destination.balance(tuesdayAsOfThursday) == 100

Let’s take this top down. The object structure we want to create looks like this:

The external API for posting a transaction seems to fit nicely as a factory method on Transaction:

class Transaction:
@staticmethod
def post(source, destination, amount, perspective):
result = Transaction(source, destination, amount, perspective)
result._post()
return result

@staticmethod
def post(source, destination, amount, perspective):
result = Transaction(source, destination, amount, perspective)
result._post()
return result

This method both creates side effects & returns a new object. Some folks would tsk tsk 🤌🏻. Too bad. Write your own code.

Supporting the factory method are the private __init__ & _post methods:

def __init__(self, source, destination, amount, perspective):
self._source = source
self._destination = destination
self._amount = amount
self._perspective = perspective
def perspective(self):
return self._perspective
def _post(self):
self._source.debit(self)
self._destination.credit(self)

An Account stores 2 Histories of Transactions, one for credits & one for debits. (Real accountants are likely cringing by now—we are using “accounts & transactions” as a metaphor, not implementing genuine double entry bookkeeping.)

class Account:
def __init__(self):
self._credits = History()
self._debits = History()
def credit(self, transaction):
self._credits.add(transaction, transaction.perspective())
def debit(self, transaction):
self._debits.add(transaction, transaction.perspective())

(I went back and forth whether to pull the perspective out here or pass it as an explicit parameter. I decided that this better expressed the invariant that the transaction is always stored under its own perspective.)

Implementation: Behavior

Now that we have the object structure we want, we can implement the balance() method.

class Account:
def balance(self, perspective):
credit = self._balanceOn(self._credits, perspective)
debit = self._balanceOn(self._debits, perspective)
return credit - debit

This relies on a helper that sums the amounts of the visible transactions in a History.

def _balanceOn(self, transactions, perspective):
return sum(map(lambda x: x.amount(), transactions.seen(perspective)))

If you remember History from the last couple of posts, we need an accessor that returns only the seen elements. Here it is for completeness:

class History:
def _seen(self, perspective):
return filter(lambda x: perspective.sees(x[0]), self._events)
def seen(self, perspective):
return map(lambda x: x[1], self._seen(perspective))

(We are inching ever closer to the dreaded range query for History, which I’m really hoping to avoid.)

Conclusion

There you have it. It would seem easy enough to implement some business logic by just querying a bunch of domain objects, writing the results somewhere temporary, summing the results, issuing a report, and then forgetting the intermediate state. This, however, would prevent you from reproducing the current state.

Instead, consider adding the additional complication of storing intermediate business results as transactions in accounts. Implement business logic by querying balances or unprocessed transactions & posting new transactions. Eventually there will be an account like “owed to customer” or “owed to government”. Processing those accounts will cause change in the outside world.

One limitation of this approach is that you can’t (yet?) easily reproduce earlier states of the code. If you process yesterday’s data with today’s logic, you could easily come up with different answers than you did yesterday. In practice this doesn’t come up that often, but it’s interesting to imagine automatic solutions. A bi-temporal code repository? Hmmm…

The ability to replay history may be surprising & novel to the business. Business invented the concept of “closing” (as in “year-end closing”) to sweep the sins of the past under the rug. Retroactive changes become exercises in accounting legerdemain. Don’t expect the business to adapt instantly.

Note that our transactions aren’t the only thing we will need to explain the history of a contract. We also need a Document Store (to be described later) to account for all correspondence sent & received.

First, a big shout-out to Massimo Arnoldi & the folks at Lifeware for teaching me these patterns. They were distilled from decades of experience operating tracking let’s just say a lot of money.

“When is she moving? When did you heard about this?” We’ve all heard this line of dialog on TV. Turns out it’s important to business system development. Here’s why.

In our previous posts, we developed the themes of this series:

• We can create value by moving some design decisions earlier, in spite of the loss of net present value.

• Business architecture is one of these cases.

• Combining human judgement & automation gives us flexibility, scalability, & efficiency.

• We have to reconcile 2 timelines—what’s going on in the real world out there & what our simplified system model knows about what’s going on, leading us to:

• Elephant Principle—remember all business information forever.

• Store data tagged by the time we stored it in the system. This lets us answer questions like, “What was the coverage last Tuesday?” (“Point queries”)

Whoopsies Happen

So far, so good. The previous model of a Customer let us get and set addresses as of dates.

Customer»setAddress(address, posting)
Customer»getAddress(posting)

Now our dual timelines come to bite us. Here’s a scenario:

1. On Monday we find out that the address is 123 Main.

2. On Wednesday we find out that the address is now 456 Main. (This customer moves a lot but not far.)

3. Whoopsie! On Thursday we find out that on Tuesday the customer moved to 789 Main.

We could just say:

customer.address(“789 Main”, tuesday)

Sort of splice the correction into the history. However, we have all of Wednesday’s processing out there based on the wrong address. How can we ask, “What address for Tuesday did I use on Wednesday?”

In other words, we want to record both:

• When this piece of information entered the system.

• When this piece of information is changed in the outside world.

Our current model conflates the two.

Enter Perspective

We need to expand the “tags” for business information. Since this tag is a way to look at the system, we’ll call it “Perspective”

class Perspective:
    def __init__(self, effective, posting):
        self.effective = effective
        self.posting = posting
    def sees(self, other):
        return other.posting <= self.posting and other.effective <= self.effective

The key piece of behavior here is that one Perspective only “sees” another if both the posting & effective times (not really just times, but we’ll get to that later) are earlier.

We use Perspective»sees() when we query a History. To find the event corresponding to a Perspective, we

1. Filter out all the events that can’t be seen.

2. Sort the visible events by effective date.

3. Return the most recent.

class History:
    def get(self, perspective):
        visible = filter(lambda x: perspective.sees(x[0]), self._events)
        freshest = sorted(visible, key=lambda x: x[0].effective, reverse=True)
        return freshest[0][1]

(Recall that events are stored as a tuple of Perspective (was justing posting) & value. All those [0]’s are starting to bug me so I’ll probably fix that soon.)

Example

Here is the code I used to drive the above implementation.

monday = 1
tuesday = 2
wednesday = 3
thursday = 4

customer = Customer()
mondayAsOfMonday = Perspective(effective=monday, posting=monday)
customer.set_address("123", mondayAsOfMonday)
tuesdayAsOfThursday = Perspective(thursday, tuesday)
customer.set_address("456", tuesdayAsOfThursday)

assert customer.get_address(mondayAsOfMonday) == "123"
assert customer.get_address(tuesdayAsOfThursday) == "456"

tuesdayAsOfWednesday = Perspective(wednesday, tuesday)
assert customer.get_address(tuesdayAsOfWednesday) == "123"

So What?

You might reasonably ask, “So what? These situations are rare.” Yes, but… First, these situations aren’t all that rare. Run a contract for 20 years & things are bound to get wobbly. Second, the cost of not tracking effective & posting separately compounds. Do you just keep running the contract even though it is wrong? Do you hire a room full of expensive actuaries to manually calculate everything? (I’ve seen both strategies used.)

The expected cost of effective/posting mismatches is high. Tracking them both, figuring out the right effective/posting combination, can be tough. It’s what we need to do to keep processing inexpensive & scalable.

I took a step too far when I introduced bi-temporality in the first post of this series. I’m going back to the beginning & start over & take one step forward.

The Big Contradiction

We want:

• The flexibility & reasoning of personal, human attention to the business problems we solve.

• But also the scalability, repeatability, & efficiency of automated processing.

If we only wanted the first goal, we could just have humans dealing directly with reality. They’d see someone disabled (‘ll be using disability insurance here as an example) & they would just pay them directly.

It’s impossible to make this consistent or scalable. We want to distribute the benefits of disability insurance as widely as possible.

The System

And so we write The System to model disability contracts. Something is lost, sure, but something is gained (we can debate capitalism & shareholder value another time—right now we’re trying to build a system that meets its goals through being more complex than the bare minimum).

The people can interact with the system or the system can act scaleably & efficiently.

The Simplest Thing That Won’t Work…

The simplest way to represent reality in the system is to record what we believe to be true at the moment. As a simplified example, suppose we have a Customer with an Address.

customer = Customer()
assert customer.address == ""
customer.address = "123 Main St."
assert customer.address == "123 Main St."

The implementation of this can be dirt simple (ignoring all the juicy stuff because addresses aren’t strings, use properties, yadda yadda yadda, not my point).

class Customer:
def __init__(self):
self.address = ""

Two Watches

When we split the world into reality out there & what we have recorded in the system, though, we have the Two Watches Problem. When you have one watch, you know what time it is. When you have two watches, you no longer know what time it is because the watches are never exactly the same & you don’t know which one is right.

We have two timelines to reconcile. Reality advances one second every second. Our system advances in fits & spurts. Sometimes we jump forward a day. Or a year. Sometimes we learn that something changed in the past & we have to repair changes we made in the meantime.

How can we handle the disconnect between reality & the system?

Save All The Data

And so we come to the first principle of business architecture—never discard information.

We are in a tradeoff space here—what is the cost of keeping information versus what is the cost of discarding information? If we discard information we save a little space, but space is cheap. We also simplify our model—there’s an address, that’s the address, end of story. However, when we discard information we are stuck when trying to explain the past. Where did you send last year’s statement? I don’t know, we have your correct address now.

If we save all historical information, we have to pay for that storage both in electrons somewhere but also in the complexity of our model. What’s the address? The address when?

For the long term economical functioning of the system, we choose to store all information that enters the system tagged by the moment it entered.

So Instead

Our interface is going to look like this.

customer = Customer()
customer.set_address("123 Main", 1)
customer.set_address("456 Main", 2)
assert customer.get_address(1) == "123 Main"
assert customer.get_address(2) == "456 Main"
assert customer.get_address(3) == "456 Main"

I moved down the street as of time 2. Instead of just setting my address, I have to also include a moment as of which the system is going record the address. Instead of just fetching my address, I have to also specify the moment as of which I want my address (we’ll talk later about the options for the type & granularity of these “moments”).

We replace the single scalar address with a timestamped collection of addresses.

class Customer:
def __init__(self):
self._addresses = History()
def get_address(self, posting):
return self._addresses.get(posting)
def set_address(self, address, posting):
self._addresses.set(address, posting)

As per usual, we cordon off the complexity of storing timestamped values in its own object, History. Setting a value is simple—just record a (moment, event) tuple. (Yes, yes, this is kind of ugly. We’ll make it better later. Chill.)

class History:
def __init__(self):
self._events = []
def set(self, address, posting):
self._events.append((posting, address))

The only cleverness to History is fetching. We sort the events in reverse order of posting time, then return the first event whose posting time is before (or the same as) the event’s posting time.

def get(self, posting):
backwards = sorted(self._events, key=lambda x: x[0], reverse=True)
for eachPosting, eachEvent in backwards:
if eachPosting <= posting:
return eachEvent
raise KeyError()

Conclusion

There you have it, our first “non-obvious complexity but I promise it’s going to pay off” decision. Save all business information forever. Tag the information with the moment we discovered it to be true.

We’re not done yet. I said jumped too quickly to bi-temporality. With the code & concepts above we’re ready to take a short step to motivating the second dimension of time—effective dating. But that’s for the next post.

“You aren’t going to need it.”

“But we are, and so…”

“You aren’t going to need it. What is the simplest thing that could possibly work?”

Pause. Thinking. “I could do this for now.”

“Okay.”

Away he went.

Curse of Knowledge

Chet’s problem wasn’t that he didn’t know enough. His problem was that he thought he had to solve an overwhelming number of problems at once. Those two mantras—”You aren’t going to need it” & “What is the simplest thing that could possibly work?”—were intended as reminders that it’s okay to do an okay job today & make it better tomorrow. In fact, because of the time value of money & the likelihood of learning, choosing to defer a decision can create value.

Lifeware

I had the good fortune last week of visiting Lifeware, a Swiss-based insurance software company I have worked with for 25 years. I noticed that Lifeware solves certain problems in a more complicated way than is obviously necessary. A quarter century of experience has shown, however, that this “over” engineering is actual the simplest, most pragmatic solution to problems that most business systems choose not to solve.

The next few posts introduce you to the Lifeware business architecture. Each post highlights an element of the architecture, its goals, & its consequences.

Overall Goal

Lifeware manages insurance contracts. It charges its customers per contract per year, so Lifeware’s sustainability depends on managing these contracts with little human intervention. However, insurance is an incredibly complex domain & programming to manage all possible scenarios is impossible.

The overall goal of Lifeware’s business architecture is mostly-automated processing of contracts with computer support when humans need to intervene. After human intervention, automated processing should resume.

Lifeware & its customers are served by achieving this goal. Policy holders & beneficiaries also benefit. Insurance is full of opaque pricing & fees. Explainable, transparent processing allows end customers to understand what they are paying for & what they are getting.

Two Timelines

As if insurance as a domain isn’t complex enough, that complexity is multiplied by operational complexity. There are 2 timelines at work—the real world & the system.

These timelines are eventually consistent. Periods of inconsistency explode the complexity of the system.

1. The customer takes out a contract in Kanton Zürich.

2. At the end of the year, the tax authorities are notified.

3. A week later, “Oh I forgot to tell you. I moved to Kanton Uri in November.”

4. Now what?

   

If we want to compute automatically, we need to:

• Identify periods of inconsistency

• Reverse & recompute the business processes that took place during inconsistency

Bi-temporality

Computing automatically requires a more complicated notion of time than the obvious. In the next post I’ll introduce bi-temporality, which we not only are going to need, but we need it now.

Software design is not about minimizing design complexity, but rather spending our complexity budget where it can do the most good.