Forem: Adam Berger

Your backend should probably be a state machine

Adam Berger — Thu, 21 Sep 2023 14:06:05 +0000

Whether you intended to or not, you’re probably building a state machine right now.

That's because any time you have a set of steps with some ordering between them, your system can be represented and built simply and visually as a state machine.

On the frontend, it’s a bit easier to squint and see the states and events you’re modeling. After all, you actually talk about transitions and "paths" the user can take through your app. The mapping from the familiar world of screens and popups and nested components to the language of hierarchical states and transitions is fairly straightforward. So, thankfully, we’ve seen more and more (though not yet enough!) adoption of state machines for modeling frontend flows.

On the backend, however, while it’s just as true that many of the systems we build are implicitly state machines, I’ve yet to see many teams explicitly model them that way.

I get it. Backend concerns seem quite different. Whiteboards in conference rooms around backend-focused teams are covered in boxes and arrows depicting information flows and architectural dependencies rather than states and transitions.

So many of us backend engineers are so consumed with the mind-boggling concurrency of our systems that we may even scoff at the idea of a system being in a "state." If the frontend seems deterministically Newtonian, the backend seems stubbornly relativistic or, on its worst days, quantum.

But our users most certainly expect that each logical grouping of their data is self-consistent. While we’re thinking about data en masse, our users really care about data in the small—this document or that ad campaign.

We’re talking about queues, eventual consistency, and reliable timers. All our users care about is having our business logic applied to their data consistently.

There is a better way. And, as is so often the case, it requires a change of perspective, a jump in the level of abstraction at which we’re working.

What we need on the backend is a focus on logic over infrastructure, an investment in dealing with the essential complexity of our business use cases rather than re-addressing the purely accidental complexity of our architecture with every new project.

The mechanism we need to accomplish that is none other than the lowly state machine.

The five sentence state machine intro

A state machine¹ definition consists of states and transitions between them. Transitions happen in response to events and may have conditions that determine whether they’re active or not. Hierarchy allows for parallel (simultaneous) states. Each instance of a state machine is in one set of states at a time (a set rather than a single state to accommodate parallel states) and owns some arbitrary data that it operates on. States can define effects that run when the state is entered or exited and transitions can define effects that run when the transition is taken; those effects can atomically update the instance’s data or interact with external systems.

This structure is easily visualized like this:

The backend state machine value proposition

We’ll talk about exactly how state machines help us solve the major classes of problems we face in backend development but, first, let’s look at the high-level value proposition.

State machines are a mechanism for carefully constraining the updates to our critical data and the execution of effects in a way that allows us to express solutions to many classes of problems we encounter and to effectively reason about those solutions.

Let's break that down.

Constraints are actually good. Like, really good. We’re all trying to build systems that perform tasks that people care about and operate in ways that we can understand, not least because we’d really like to fix them when they misbehave. Unconstrained code leaves no bulwark between our too-burdened brains and the chaos of executing billions of arbitrary operations per core every second. We all consider GOTOs harmful because Djikstra convinced us that we should aim to "make the correspondence between the program (spread out in text space) and the process (spread out in time) as trivial as possible."

There are few better ways to simplify the correspondence between what your program looks like and what it does than by constraining your program’s high-level structure to a state machine. With that reasonable constraint in place, it suddenly becomes trivial to understand, simulate, and predict what the systems we build will actually do.
Protect your data and orchestrate your effects. Just as the infrastructure of our system only exists to support our business logic, our business logic only exists to act on our data and the external world. Data updates are forever and the changes we effect in the world or external systems can have serious repercussions.

As we saw above, with state machines, data updates and effects are only executed at specific points, with clean error handling hooks, and easy simulation. When you know exactly where and under which conditions these critical actions will happen, your entire system becomes intelligible, invariants become comprehensible, and your data becomes trustworthy.
Reasoning about your system is not optional. There’s the old adage: "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it." Kernighan said that in the era of standalone programs. How quaint those times seem now. Once you connect two programs together the emergent effects of your system—unexpected feedback loops, runaway retries, corrupted data—create a mess many orders of magnitude more “clever” than any one component.

If we’re going to have any hope of understanding the systems we build—and we better, if we want them to do useful things for people—then we have no option but to constrain ourselves to simple parts. Because they are so simple, state machines are just the right high-level structure for the components of a system you hope to be able to understand.
We left off expressiveness. Expressiveness is the point at which I hear the groans from some of the folks in the back. We've all been burned by the promise of a configuration-driven panacea before. What happens when your problem demands you step beyond the paved road that the platform envisioned? And so began the rise of the "everything as code" movement that's now ascendant. It makes sense. You simply can't forego expressivity because expressivity determines your ability to solve the problems you're faced with. It's non-negotiable.

But expressivity is the key, not arbitrary code executing in arbitrary ways. State machines are expressive enough to model processes in any domain, naturally. They simply provide the high-level structure within which your code executes. This constraint ensures you can naturally express your logic while preserving your ability to model the system in your head. Even non-engineers can typically understand a system's logic by looking at its state machines.

Now, let's look at the two primary types of backend systems and examine how state machines might form a helpful core abstraction for each. First, we'll examine reactive systems and then proactive systems (aka, workflows).

Reactive systems

Most of our APIs fall into this camp. Get a request, retrieve or update some data, return a response; they lay dormant until some external event spurs them to act.

Whether we write these as microservices, macroservices, miniliths, or monoliths, we have a bunch of seemingly-decoupled functions responding to not-obviously-connected requests by updating some very-much-shared state.

A reactive system example

Let's look at an example to understand how state machines can help us build better reactive systems. We’ll walk through the traditional way of building a traditional app: a food delivery service, focusing on the flow of an order.

We’ll simplify the flow to this: users submit an order, we offer it to the restaurant, the restaurant accepts or rejects it, and a bit later, we send the delivery request to a courier and wait until the courier marks the order complete.

To build that in a traditional way, we’ll probably want an order service with endpoints for users to create an order, restaurants to accept an order, couriers to accept a delivery and mark it complete, and timers to notify us that they’ve elapsed.

To wildly simplify what was, in my past job, a few hundred person-years of work, you likely put together some code structured like this:

To represent a process that I’m pretty sure you’re picturing in your head right now like this:

Expand

The problem with the traditional approach

It looks like those endpoints sitting in their separate files are decoupled but, within each route, we have a bunch of assumptions about where we are in the flow. Orders can only be accepted once, couriers need the order information we stored during order acceptance when they pick up the order and shouldn’t be able to accept early since they’re paid based on time spent. We’ll also need to make sure that, if we offer a job to a courier who rejects, they can’t subsequently accept after another courier is assigned.

In short, to be correct, each endpoint must validate aspects of the overall flow so, to coherently understand this system, we need to think about the whole thing—we can't really understand any part in isolation. The overall process is what our customers are paying for, not a set of endpoints. Having spent many sleepless nights attending to outages within just such a system, I know firsthand that seemingly innocent changes to a supposedly isolated endpoint can have unintended consequences that ripple through the entire system.

Basically, all of the critical structure around and between the endpoints that jumps right out at us in the state machine is completely hidden and hard to extract from the "decoupled" endpoints.

Now, let’s imagine an all-too real request: after building this system, our business team decides that we could offer wider selection faster if we send couriers out to buy items from restaurants we have no relationship with (and, therefore, no way to send orders to directly).

With that feature, we’ve broken all of the assumptions buried in our supposedly decoupled endpoints. Now, couriers get dispatched first and orders are accepted or rejected after the courier is on their way.

With the traditional structure, we satisfy this new requirement by painstakingly spelunking through each of our endpoints and peppering in the appropriate conditionals, hoping that, in the process, we don’t disrupt the regular orders flowing through our system.

Then, to satisfy restaurants that want to perform their own deliveries, we add a new option: for some orders, instead of dispatching couriers, we give the restaurant the delivery information so they can bring the customer their food. We wade through the mess of conditionals in our "decoupled" endpoints, struggling to trace distinct, coherent flows, painstakingly adding to the confusion as we implement our new feature.

Doing better

The trouble here lies in the difference between coupling and cohesion. Most systems have some degree of coupling, some interdependent assumptions between different endpoints or components. The degree of coupling is directly related to the difficulty of understanding a part of the system separately from the whole. As it becomes harder to understand this endpoint without also understanding those endpoints, it becomes more and more important to treat the system as a cohesive whole rather than pretending each part is an isolated component.

As the coupling between endpoints grows, so too do the benefits of representing the system as an explicit state machine.

If you’re blessed with a generally stateless problem domain where you can build truly isolated endpoints, you should certainly do so! Our goal is always simplicity in the service of comprehensibility and, by that measure, nothing beats an isolated pure function.

If, however, your problem domain, like most, requires inter-component assumptions, I highly recommend that you architect your system as it is—as a whole—instead of pretending it is composed of isolated pieces. As the dependencies between the endpoints of your system intensify, you’ll find more and more value from representing your requests as events sent to an instance of a state machine and your responses as pure functions of the machine’s state and owned data. In these systems, your primary concern is to understand the inter-component flow and that’s exactly what a state machine provides. You then build truly decoupled data updates, actions and conditions that your state machine orchestrates into a coherent whole.

Returning to our example, it doesn’t take a state machine expert to be able to understand our complex, 3-part flow from this executable diagram but I can assure you that after 6 years in the trenches with the "decoupled" endpoint version of this system, I still struggled to piece together a view of the what the system was actually doing.

Expand

By making this shift, we can solve the general problem of running consistent instances of these machines once and then spend all of our time building the business logic our users actually need.

Which brings us to our second class of system…

Proactive systems (workflows)

Proactive systems are distinguished by being primarily self-driven. They may wait on some external event occasionally, but the primary impetus driving them forward is the completion of some process or timer they started.

The fundamental problem with workflows is that computers run code as processes and, while processes are permanent(ish) at the timescale of a request, they are decidedly ephemeral at the timescale of a long-lived workflow. We used to string together cron jobs, queues, and watchdogs to ensure forward progress in the face of machine and process failures. That made things work but created a mess—as with the "decoupled" endpoints we saw above, there was no cohesion to the separately-deployed dependencies. All of the above arguments for building more cohesive systems apply doubly so for workflows built around queues, event buses, and timers—understanding a system from those parts demands top-rate detective work.

Workflow engines and the clever hack

In the past few years, we’ve seen the rise of the cohesive workflow as an abstraction in its own right². Just write code and let the workflow engine deal with reliably running on top of unreliable processes. Wonderful! Except that nearly all such platforms suffer from two major flaws: a lack of upgradability and embracing an iffy, leaky abstraction.

There is only one constant across every software project I’ve seen: change. We’ve created this infinitely malleable construct and—of course!—we’re going to take advantage of its amazing ability to change. But there is no coherent upgrade story for any major workflow platform. After kicking off a job that’s going to run for a year, there’s no reasonable way to change how it works!

The best of these systems allow you to litter your code with version checks to manually recover missing context. Understanding is the hardest part of the job and trying to reason about a workflow littered with “if (version > 1.123) {...}” checks is like betting your business on your ability to win at 3d chess—we shouldn’t need to introduce a time dimension to our code.

This obvious problem of wildly complicated updates derives from the less obvious, more insidious issue with workflow platforms: at their core is a Shlemiel the painter algorithm. They cleverly provide the illusion of resuming your code where it left off but that’s simply not possible with the lack of constraints present in arbitrary code, where any line can depend on arbitrary state left in memory by any code that previously ran. They provide this illusion by running from the beginning on every execution and using stored responses for already-called effects, thereby re-building all of the in-process context that your next bit of code might depend on.

It is clever!

It is also the wrong abstraction because it starts from the assumption that we programmers aren’t open to adopting something better than arbitrary, unconstrained code.

A better abstraction

With state machines as the core abstraction for workflows, upgrading becomes a simple data mapping exercise because we know exactly what any future code depends on: our state and our owned data. We can write one function to map states from the old version to states from the new version and one function to map the owned data from the old version to owned data from the new version. Then we can upgrade instances of our state machine whenever we want and our logic itself can ignore the history of mistakes and rethought features that more rightly belong in our git history than our production deployment.

There’s more. State machines are inherently resumable because, again, we know exactly how to rebuild the state that any future execution depends on: just load the state and owned data. No clever tricks required.

A workflow example

Let’s look at an example of an onboarding workflow we might run with a standard workflow engine today:

export async function OnboardingWorkflow(email: string) {
 await sendWelcomeEmail(email);
 await sleep("1 day");
 await sendFirstDripEmail(email);
}

Workflow engines treat each of our awaited functions as "activities" or "steps", recording the inputs and outputs of each and providing us the illusion of being able to resume execution just after them.

Now, we decide that we want our welcome email to vary based on the acquisition channel for our user. Simple, right?

export async function OnboardingWorkflow(email: string) {
 const acquisitionChannel = await getAcquisitionChannel(email);
 await sendWelcomeEmail(email, acquisitionChannel);
 await sleep("1 day");
 await sendFirstDripEmail(email);
}

Nope! If a user has already passed the sendWelcomeEmail step, workflow execution engines have no choice but to throw an error or send a second welcome email with this change. Let’s see why.

The first time the workflow runs the first version of our workflow, the engine will execute the sendWelcomeEmail activity and store its result, then execute the sleep activity, which will register a timer and then throw an exception to stop the execution. After the timer elapses, the engine has no way³ to jump to the line of code after our call to sleep. Instead, it starts at the very top again and uses stored results for any functions it already executed. It has to do this because there’s no other way to rebuild all of the program state that we might depend on (e.g. local variables, global variables, arbitrary pointers, etc.). Instead, we’ll need to write our updated version more like this:

export async function OnboardingWorkflow(email: string) {
 if (getVersion() < 2) {
    await sendWelcomeEmail(email, defaultAcquisitionChannel);
 } else {
   const acquisitionChannel = await getAcquisitionChannel(email);
   await sendWelcomeEmail(email, acquisitionChannel);
 }
 await sleep("1 day");
 await sendFirstDripEmail(email);
}

Now imagine that we had more updates (great software engineering teams push multiple changes a day, right?) and imagine that the steps of our workflow had more direct dependencies between them. Maybe you could still mentally model the overall flow after v3. What about after v7?

Again but with a state machine

With state machines, things are a bit different.

We start with this state machine:

Expand

For simple workflows, this diagram is helpful but it’s admittedly not a huge improvement in understandability over the code. As things get more complex though, a visual representation of the high-level structure of the workflow is really helpful. More importantly for our analysis here though, this is what an upgrade looks like:

Expand

As an engineer, we need to do 3 things to cleanly migrate running instances from one version of our machine to another:

We build the new version of our state machine. We don't need to include any vestiges of the old version that are no longer needed. This is represented in the right-hand side of the above diagram.
We write a function to map our old states to our new states (a trivial mapping in this case). This is represented as the left-to-right arrows in the diagram.
We write another function to map the owned data for the old version to owned data for our new version of the machine. For example, if we had used the acquisition channel in future states, we would want to populate the acquisition channel in our owned data as part of this mapping.

Because of the constraints of state machines, those mapping functions are straightforward to write and easy to test.

This upgrade mechanism allows us to keep our workflow implementation clean and completely separate from our handling of changes over time. The inherent ability of state machines to actually resume execution from any state is what allows us to disentangle our change history from our point-in-time state machine definition.

Putting them together

Examined more broadly, few systems fall entirely into the reactive or proactive categories. An application likely has reactive aspects that kick off proactive processes that wait for reactive events and so forth. With today’s paradigms, these are incredibly awkward to model uniformly, so we tend to create subsystems built around different abstractions with different operational teams with different expertise. Because state machines are driven by events and are inherently resumable, they easily model both reactive and proactive systems within a single paradigm that’s able to naturally express both types of solutions.

Migrating

Great! So now that you're convinced of the value of state machines, you just need to rewrite your whole backend as a set of state machines in a big, all-at-once migration, right?

Not quite.

You don’t need to replace your existing code with state machines. In many cases, you’ll want to wrap calls to your (simplified) existing code in a state machine. That’s because, for most backends, the entire concept of a flow is simply missing. Once you introduce a state machine that’s responsible for executing the code that previously sat behind your endpoints, you can update your clients or API layer to send events to your new state machine instead of directly invoking the endpoints. Then, you can remove the flow-related checks and logic from the former endpoint code that now sits behind your state machine. Finally, you can lift your state management out of the former endpoint code to move ownership of the data to the state machine itself.

Obviously, all of this can be applied just to new projects and migrations can easily be approached piecemeal, wrapping one related set of endpoints at a time.

Let's examine the value gained at these key milestones:

Creating a state machine to wrap a set of endpoints will yield valuable insight into the system you thought you knew. This executable documentation will allow future engineers to understand the overall flow and confidently make changes. You'll even remove the potential for a whole class of race conditions. Often, you'll discover never-before-considered user flows lurking in your existing implementation and this is a great time to finally define how they're supposed to work.
Pulling the flow-related checks and validations out of the former endpoint code will simplify things as only deleting code can. You'll likely even find a few lurking bugs in those complex validations.
Lifting state management out of the former endpoint code and into the state machine removes yet more code with yet more potential for bugs. Importantly, you'll find that your next project finishes faster and with fewer outages because you've pulled many application concerns up to the platform level.

Getting started

Ready to start implementing your backends as state machines?

The most important first step is to start thinking in terms of states and transitions. Immediately, you'll start to see improvements in your ability to understand your software.

There are even some great libraries you can use to build state machines on the backend, including XState.

And there's a new service that can definitely help you adopt this pattern...

I was lucky enough to be a part of Uber Eats' journey from an endpoint-oriented to a workflow-oriented architecture. Complex dependencies between endpoints had made working on them incredibly difficult and error-prone. With the migration to a workflow abstraction, we gained immense confidence in our system by finally having a cohesive view of the user-relevant flows that we were building.

This was super exciting but, as I'm sure you can tell by now, I saw huge potential for state machines to expand upon that value. So I started State Backed. We recently released our state machine cloud to make it incredibly easy to deploy any state machine as a reliable workflow or a real-time, reactive backend. We'd be proud to help you adopt state machines for your own backend or we're happy to share notes and help however we can if you choose to build a state machine solution yourself.

You can have a state machine deployed in the State Backed cloud in the next 5 minutes if you'd like to try it out.

Try State Backed for free

Technically, we’re talking about statecharts throughout this article because we want the expressivity benefits of hierarchical and parallel states. We’ll use the more common term just for familiarity. ↩
This was pioneered by platforms like Cadence. These platforms were a huge leap forward for proactive system design because they enabled cohesion in this type of software for the first time. The fact that we believe that state machines are a more suitable abstraction doesn't detract at all from the amazing advance that these platforms made. ↩
The only exception we’re aware of is Golem, a workflow engine built around Web Assembly. You can't snapshot the memory of a regular process and restore it but, because of Web Assembly’s sandbox model, they are able to capture the full program state and do actual resumption. This is a beautiful abstraction for resumption but doesn't address upgrading running instances. ↩

Introducing... the Team Pando flow editor

Adam Berger — Thu, 08 Jun 2023 15:04:08 +0000

You can now easily edit your Team Pando product flows

Last week we gave you a sneak peak into how we use Team Pando to build features for Team Pando.

That feature has now been live and used by amazing members of Team Pando for a few days so we thought it was time to officially share a demo with you all.

First, a reminder about what we built.

Team Pando's Requirements Understanding Engine is the world's first and best engine for extracting the structure from the normal product requirements we all write every day. We turn requirements into product flows that faithfully represent the product that you're defining.

When the flows that we generate are slightly different from what you expected, your first choice should be to update the requirements to clarify your intention. We recommend that as the first choice not because it will help our Requirements Understanding Engine but because it will help the rest of your team understand exactly what you have in mind.

Sometimes, though, you just want to make a quick change. In those cases, Team Pando now let's you easily make changes to the flow we created for each requirement.

Check out flow editing in action, below.

Or open up Team Pando and try it out for yourself!

Product building blocks

Adam Berger — Wed, 07 Jun 2023 21:12:12 +0000

From humble beginnings...

Simple things can give rise to enormous complexity.

The same 4 DNA bases and 20 amino acids make chickens, humans, tulips and whales
Transistors just switch on and off but enough of them can now mimic human intelligence
The interactions between 4 fundamental forces give rise to all of physics

In field after field, discovering and deeply understanding the right "atoms"--the right building blocks--to describe the complex phenomena we see creates an explosion in our ability to shape our world.

But every product is unique, right?

It would seem that each software product is a bespoke beast, with SaaS apps made of completely different "stuff" than a consumer marketplace. Just as it wasn't obvious that the same building blocks and processes produce humans and slugs or that just 4 forces account for everything we see happening in our Universe, it's not immediately obvious that there are universal building blocks for products.

But if there were atoms of products, surely we would want to use them, right?

In field after field, thinking small, from the atoms up, has yielded huge advances in our ability to build big. We think that product building is no exception.

Atoms of products

It turns out that there actually are a small set of atoms that all products are made out of.

And that's what we put at the center of Team Pando.

We can make every product out of:

States or steps. A product is in one or more state(s) at any given time and the states determine what the user and product can do.
Events. Events are anything that a user or external actor can do. These are things that our product might want to respond to in some way. Clicking, tapping, typing, etc.
Conditions. Conditions determine how our product will respond to a given event. For instance, you may want an "is valid" condition determining what effect a form submission event should have.
Actions. Actions are things that the product can do. Saving data, recording events, messaging other systems.

And we've found that there's one additional atom that really helps us stay at a comfortable level of detail while we're specifying products:

Expectations. We can be explicit about how we expect our product to represent certain states.

That's it. With those building blocks, you can describe any product you've built or interacted with.

What about the UI?

So you actually want to interact with this product you're building? ;)

Our building blocks just specify the different steps that a product has, what's expected at each step, and what the user and product can do at each step. But we haven't mentioned anything about how users actually do those things yet.

The answer is fairly beautiful: the UI is determined by which state(s) the product is in. Think about it: the state determines what a user can do, it has associated expectations describing how the user might do some of those things and it comes with a map of where the user can go next. That sounds a lot like a design spec to us! That's why we connect designs to states in Team Pando.

Our transistor moment

We have found that representing products this way has huge benefits.

We can build up a common vocabulary across a team.

We can be perfectly precise in talking about our products.

We can connect everyone's work to the same blueprint, keeping teams tightly aligned.

We can generate documentation, walkthroughs, help content, tests, and code.

We can identify inter-team overlaps and conflicts while everyone is still in the ideation phase.

We certainly didn't invent this model (you can learn more about state charts here) but we are big believers in its ability to help us think clearly, together. Try out Team Pando with your team and tell us what you think!

End-to-end product lifecycle with Team Pando

Adam Berger — Tue, 30 May 2023 21:58:35 +0000

Eat your own dog food. It's good for you!

There is nothing like eating your own dog food to build empathy with your users and there's nothing that comes close to real user empathy in its ability to improve your product.

We're lucky at Team Pando: we're a product team who loves helping product teams build better products, faster.

So we get to use our own product every day to build... our product.

Here's a view into how we use Team Pando to build Team Pando. (And look out for the feature we discuss to drop in the product soon!)

How do you manage your product, design, and engineering handoffs? If you like what you see, check out Team Pando — we’re here to help!

Say Hello to Team Pando

Adam Berger — Mon, 22 May 2023 17:52:48 +0000

We'll start with the bad news...

Building great software is just too hard.

Great products are wildly complex. Not in the sense that they expose wild complexity to users but in the sense that the team of people building them have to deal with a staggering amount of complexity.

For every step a user takes, a product team had to consider the dozens of steps they didn't take and how each of those dozens of steps might have influenced the thousands of future steps that user might take.

But wait... There's more.

Few products are built singlehandedly. Product managers, designers, engineers, data scientists, quality assurance, product marketers, and operations teams all need to have the same, shared understanding of the key details of the product they're building. Once the picture of the product everyone carries in their mind starts to drift, the end result is as expected: a bit blurry, a bit too much friction, parts that almost fit together, and late-in-the-game delays.

But there's a better way.

And it just so happens that the path forward addresses both of the fundamental problems facing product teams today: product complexity and team alignment.

The answer is to make the structure of the product itself real and to use that structure as the connective tissue for everything the team builds.

And that is what Team Pando does.

You already write requirements

Team Pando turns them into flows.

Looming problems become obvious while you're still defining the product
Experiencing the product from a user's perspective is a click away
One shared vocabulary for the whole team

You already make designs

Team Pando syncs them with your requirements and the key parts of your flow they relate to.

Use our Figma plugin to auto-create Figma frames for each step in your flow
We'll sync just the relevant requirements right into your Figma files
We'll auto-generate clickable prototypes from your designs based on your flows

You already do engineering handoffs

Team Pando makes them a breeze with walkthroughs that put everything an engineer needs to build every step of every flow right at their fingertips.

Engineers have all of the designs, requirements, context, and collateral they need; no more searching through chats and docs
Engineers can download an executable version of the flow as a state chart
Auto-generated tests mean QA isn't chasing after the rest of the team

What better to align your whole team to than the product that they're building?

Team Pando brings the structure of your product front and center and then connects all of your team's work to the key pieces of your product

Try Team Pando for free and stay tuned for more exciting updates soon!

A serverless, versioned, local-first data syncing backend

Adam Berger — Tue, 20 Dec 2022 16:55:03 +0000

We’ve been busy here at Simply Stated. We’re still building Omniscient XState Observability but it’s now part of a much more ambitious project. We’ll talk more about our expanded vision soon but we thought it would be fun to share some details about an interesting architecture we’ve been working on in the meantime.

We are building a collaboration product for serious work. We call the core document that users will be collaboratively working on a project. Like other collaboration apps, we want to make sure that multiple users can edit a project in real time, everyone can see each others’ edits quickly, and edits don’t conflict with each other in a user-visible way.

We settled on this set of requirements:

Within a project, all user interactions should be local-first and snappy.
Clients should be able to sync their changes to our backend, which will determine their canonical ordering and, therefore, the succession of canonical versions. We don’t need peer-to-peer consensus.
We should be able to replay all of the updates (we call them mutations) for a project on top of a different starting state, similarly to a git rebase.
Mutations may be reordered across clients but must be applied in-order for a particular client. That is, the client orderings define a partial order over the set of mutations.
We must be able to scale to any number of projects and to large histories within a project but won’t see more than double digit mutations per second within a project.
We prefer to use autoscaling, serverless components.

We stand on the shoulders of giants

A major thank you to Replicache, Figma, and, as usual, Rich Hickey, this time with Datomic for sharing their thinking about similar problem spaces.

The high-level scheme

We will take a Replicache-like approach of encoding mutations as data (similar to a redux action). On the client, we’ll compute our current state by applying all local mutations to the canonical data we last received from the server. We’ll send a batch of mutations to the server, where the server will decide how to apply them to the now-current canonical data, which may differ from what the client believed to be the canonical data when it applied those mutations. The server-side application of a particular mutation might not result in the same state as the optimistic, client-side application of that mutation and that’s ok! The mutation logic will handle our conflict resolution. After the server applies mutations, it will send the client back the new state and the ID of the latest mutation it applied. The client can then update its canonical state and apply all local mutations after the latest mutation included in the canonical state.

First, our datastore selection

Typically, we start with consistency requirements to determine our datastore. Do we need multi-key transactions, compare-and-swap semantics, etc.? Due to other architectural choices we’ll talk about later, the only consistency guarantee that we actually require of our datastore is read-after-write consistency. That is, we need at least the option of performing a read that will return the data inserted by the most recent write. And because we’re maintaining a version history, we’re actually able to run entirely append-only, so update semantics don’t matter to us.

Within the AWS ecosystem, both DynamoDB and S3 support read-your-own write consistency models. Dynamo supports a ConsistentRead option on queries and S3 (miraculously!) supports strong read-after-write consistency for all operations.

Data modeling

First, we’d like to share just a bit about the data we’re working with.

Projects–our primary versioned entity–are composed of a few scalars (things like name, description, etc. that we can restrict to ~1.5kb max, typically <250 bytes) and a few (we have 2 right now) collections where the cardinality of each collection is fairly small (hundreds would be very rare) but the items in the collections are rich, potentially medium-sized (tens to hundreds of kbs) structures. We’ll assume we have some long-lasting identifier for a particular client (an entity collaborating on a project), which we’ll call a client ID.

Before we look at our write path, let’s examine the queries that we’ll need to make.

We (fairly rarely) need to retrieve the latest version for a project along with all of its collections and their items.
We need to retrieve a list of metadata (name, id, etc. but not the full data) for all of the items within collections.
We need to retrieve a specific item by ID from a specific collection from the latest version of a project or a specific version of a project.
We will (rarely) need to list all of the versions of a project in order and should be able to see the full project state and the (ordered) mutations that were applied to produce any given version.
We will need to query for whether a given mutation has already been applied.
We will need to query for the latest mutation from a given client that has been applied to any version of a project.

First, let’s look at some simple approaches.

In a relational model, we could transactionally copy every record related to a project, re-write all of them for the new version, and store an ordered list of client IDs and their mutations, as they were applied.

Somewhat similarly, we could store all of the data for a project in one record, either entirely in DynamoDB, entirely in S3, or in DynamoDB but spilling out to S3 if we exceed the 400kb record size limit. Then, whenever we process an update, we can take out a lock, read everything for the project, apply the mutations, and write everything for the new project version along with a list of client IDs and mutations.

These approaches share a common issue: significant write amplification. That’s an effect where a small change to one part of one item in a collection would require writing the entire structure again. As we said, some of these structures may be large-ish and DynamoDB charges per 1kb chunk on writes. Even with compression, we would be duplicating quite a bit of repetitive data, driving up costs.

However, we would be able to fulfill all of our query needs with these approaches in any of our potential datastores in a fairly reasonable manner (S3 would appear trickier here but S3 Select would allow us to retrieve only the portion of the content that we needed). Unfortunately, while DynamoDB and S3 allow us to project only a portion of our data for queries, they charge based on the full object size.

We were concerned about the cost of DynamoDB storage and writes with so much write amplification, and were concerned about the storage costs of duplicating everything for every project version in S3.

So we decided to take a multi-tier approach to our data storage, inspired partly by git and partly by Datomic. We’ll divide our data into versioned entities and blob entities.

First, we’ll define a level of granularity at which we’ll treat data as content-addressed blobs. Above that level of granularity, we’ll maintain versioned records that point into those blobs. For us, we defined items within collections as our blob layer and everything above that as our versioned layer. So, for example, projects, and collections are monotonically versioned while collection items are content-addressed. We’ll store our blobs in S3 and our versioned entities in DynamoDB. This allows us consistently fast access to versioned entities and their metadata without suffering from the full write amplification that came along with the simple approaches we discussed above.

We store our blobs (each collection item) in S3, content-addressed, under the project namespace using a key of the form: …/{sha256(item contents)}.json.gz.

We store the project structure, with pointers to our content-addressed items, in DynamoDB, using a single-table schema to satisfy all of the queries we mentioned above. As we’ll see, in our usage, a single DynamoDB table is used more for its scaling and cost benefits than for its query benefits.

Let’s take a look at our DynamoDB data. We have four types of entities that we’ll be storing: projects, project versions, collection versions, and mutations.

First, we store our project IDs by the organization that each belongs to. This data is essentially write-once, at project creation, and supports listing the projects for an organization by querying by the partition key or retrieving the organization for a project by querying the inverted index by project ID.

Next, we have our project versions. Project versions are keyed by the project ID they belong to and have a lexicographically increasing version number. This allows us to easily query for the most recent version. Each record contains the scalars we mentioned for the project and points to the version number of each collection for the project. We also store an ordered list of mutations that were applied to produce that project version.

We already introduced our collection version numbers in our project version schema. Each new version of a collection within our project (e.g. adding or modifying an item) has a record, keyed off of the project ID and the collection name and version number (+ a sequence number in case we need to spill over multiple records due to Dynamo’s 400kb item limit, a very unlikely scenario). Each record contains a map from item ids to the hash of the item’s contents, which is its address in S3. So, if we want to lookup the items for Collection1 for project p_4567, we can first query for the latest project version (pk = “Project#p_4567” and begins_with(sk, “ProjectVersion#”), sort descending by sort key, limit 1), get the collection1Version from it, then query for the collection version (pk = “Project#p_4567” and begins_with(sk, “Collection1#c1v_000002#”)), and lookup the collection items in S3 using the provided versions. With some clever query logic, we can actually optimize out the project version lookup by taking advantage of our monotonic collection versions.

Finally, we have our mutations. We add a record for every mutation to our project, with a partition key that includes the project ID and a sort key that includes the client ID and the mutation ID, where it is the clients’ responsibility to ensure monotonically-increasing mutation IDs.

Example

So, let’s look at how a simple processor would deal with a batch of mutations for a particular project.

Imagine we start with data like this, representing a project whose name was just changed from “My project” to “My project (edited)” in the same “commit” as the contents of the “id1” item in collection 1 changed such that its hash was “abc” but is now “xyz”:

Then, one client with client ID c_client1 submits a mutation with ID “m_mut1” to modify the item with ID “id1” in collection 1 of project “p_4567”.

‍

The processor performs the following:

1. Check if our mutation has already been applied

1a. Query for pk = “Mutation#c_client1#m_mut1” and begins_with(sk, “Project#”)

1b. We see that the mutation has not yet been applied so we continue

2. Find the current project version (we can optimize out this query depending on our query patterns)

2a. Query for pk = “Project#p_4567” and begins_with(sk, “ProjectVersion#”), sorting descending.

2b. We find this item:

3. Query the collection version to find the pointer to the data for the id1 item in S3

3a. Query for pk = “Project#p_4567” and begins_with(sk, “Collection1#c1v_000002#”)

3b. We find this item:

4. Load the id1 item from S3 with key: /o_123/projects/p_4567/Collection1/def.json.gz

5. Execute our mutation against the id1 data

6. Hash the new contents of id1 to determine the new version identifier, let’s call it newHash

7. Write id1 to S3 at key: …/{newHash}.json.gz

8. Increment the project version number (pv_000010) to find our new project version: pv_000011

9. Increment the Collection1 version (c1v_000002) to find our new Collection1 version: c1v_000003

10. Transactionally write our updates:

11. Now, we’ve stored our new id1 item in S3, wrote our new collection version, pointing to the id1 item in S3, appended our new project version, pointing to our new collection version, and wrote a record of our mutation.

Guarantees

Now let’s examine what could go wrong.

Other mutations to the same project could have been submitted and may be processed concurrently. Specifically, if both mutations read project version x, apply their mutation, and write project version y, one of the mutations will have been effectively dropped. We will address this below.
Our processor might fail and the requester might retry. We apply mutations idempotently, performing a consistent read to skip processing already-applied updates and, because we wrote our mutation record transactionally with the project version update, we won’t double-apply a mutation. As long as the requester continues to retry, we will eventually apply the mutation. Outstanding issues: we need to ensure that clients perform retries and we need to ensure mutation ordering within a given client in the presence of retries.

Architecture

We still have some outstanding issues that our datastore structure left unaddressed. Specifically, we need to ensure that mutations are retried, we need those retries to remain ordered across retries and new mutations coming from the same client for the same project, and we need to ensure that only one processor is applying mutations to any given project at any given time.

To satisfy those requirements, we will use an SQS FIFO queue with each message specifying the project ID as its MessageGroupID. We will configure a lambda processor for our queue, fulfilling our serverless goal.

Let’s ensure that we’ve addressed our outstanding issues:

We trivially satisfy our retry requirement. Lambda will only delete items from the queue after they have been successfully processed (or written to a dead-letter queue) and we already ensure idempotency.
FIFO queues are designed specifically to ensure that items within a message group are processed in the order in which they were added to the queue. As long as our clients send their mutations in-order, this architecture ensures that, regardless of retries, all mutations for a given project for a given client will be processed in the same order in which they occurred on each client.
FIFO queues are also designed to ensure that no other items from a given message group will be dispensed while other items from that group are in-flight. This ensures that only one processor will process mutations for a project at any time.

The client side

We’ll cover the client side of our sync solution in another post. Stay tuned!

Sorry to tell you this but your epistemology is showing

Adam Berger — Wed, 07 Dec 2022 15:43:11 +0000

We're still a young industry. We've been building bridges for a few thousand years and we've only been building software products for a few decades. We've discovered some hard and fast rules for building better software products but much of the wisdom we've acquired now gets bandied about in the form of maxims, many with a kernel of deep truth, but passed around without context.

Engineers throw around phrases like YAGNI ("you ain't gonna need it") and "premature abstraction is the root of all evil" in well-intentioned attempts to prevent their colleagues from indulging in what we've commonly branded "over-engineering." Product managers champion "ruthless prioritization," justifying a compelling minimalism, forever under threat from the siren song of "more."

These ideas are important and stem from deep, fundamental truths about the nature of the products we build.

But, as with everything in our industry, context matters. A command--any command--, divorced from its purpose, is a dangerous thing. That's why so much of a product manager's time is spent understanding and then building empathy for the real problems users face and the actual jobs they seek to accomplish with the product the team is building. That's why--often--the majority of an engineering manager's job is spent reinforcing the purpose of the team's work, connecting the code to the outcome.

"Why" matters.

So, let's examine the why behind these minimalist maxims. What truth about our products underlies them and what determines their applicability? When and why aren't you gonna need it and when might you? When and why should you abstract and when should you solve only the immediate problem? When and why should you "ruthlessly" prioritize and when should you pursue the mythical p3, only so named because we had so many p1s we decided to make a new p0 category?

The answer lies in epistemology.

But first, let's agree on what our job is as a member of a product team. Our first instinct might be to say that we are solving user problems and enabling users to more efficiently accomplish the jobs they have to do. Unfortunately, the most direct way to accomplish that is not through software; it's by sitting down with them as their assistant. Our actual job then involves solving those user problems at scale, more efficiently than can be done by assigning more and more smarter and smarter humans to each customer. How then are we to accomplish that? By building in malleable software a model of the domain that our users work in, allowing them to easily map domain-level concepts to product-level concepts and domain level operations to product-level operations.

That's it. That's the primary job of every member of a product team: product manager, engineer, designer, copywriter, etc. Build a coherent model of the domain your customer is working in and allow them to easily map the things they want to do in the real world onto your representation of it, to manipulate that representation of the thing they actually care about, and then to map back from your representation into the real world.

If we do that well, our users don't even realize they're doing this mapping. They see a file and they drag it into a folder because that perfectly matches their mental model of what they want to do (for some version of a 1980s-era customer who still knew what a file folder was and once handled physical pieces of trees with writing on them).

That may sound easy but it is likely the hardest thing humans have attempted to do.

We've been trying to categorize things and create ontologies for our world for about as long as we've been using language.

And exactly what rules govern that process and how best to approach it is still an unresolved question but the basis for any answer lies in how we understand reality, how we understand what’s true and what isn’t and why.

Epistemology is our attempt at answering the question: what's true and how do you know it's true?

That’s our route to improving the way we build and evaluate our models of the world.

So let's get back to our favorite product-building aphorisms.

Historically, everything was built in a full waterfall model with a big design up front and implementation at the end. This reflects a perspective of epistemological certainty, a belief that everything is knowable and prestatable.

The maxims we mentioned at the beginning (ruthless prioritization, YAGNI, premature abstraction) all embody a reaction against the obvious absurdity of total epistemological certainty; they reflect a complete embrace of epistemic uncertainty, of the idea that the world is inherently or effectively un-modelable, un-prestatable, and--to a large extent--un-_know_able.

Unfortunately, both worldviews are wrong in their absolutism. The obvious reality for anyone who has spent much time observing the world is that some things are knowable and prestatable and some things are not. And some things are knowable in principle but we just don’t know them yet.

Now, this does not imply that each category of thing is partially knowable. The truth rarely lies in the middle. It means just what we said: some things are knowable and some things are not knowable. In some areas, you can design up front and get it right and in other areas, you just have to iteratively unfold your product, letting it co-evolve with your user base.

The correct epistemic stance--and, therefore, the correct product development methodology--depends on the domain you're modeling.

Many things in the domains we care about have natural algebras, a set of objects and expected relationships between them. A collection of things, for example, can be set-like or list-like and we know quite well what types of things people do with set-like or list-like objects. To pretend that you know you want an add operation for a set-like thing (like user permissions) but that we can't possibly tell in advance if a delete operation is necessary or what its priority is doesn’t quite pass the smell test after millennia of human experience working with sets of things. There is regularity in nature in the way that objects relate to each other and that regularity underlies the domains we care about. It's our responsibility as product builders to recognize the true nature of the objects we're representing and to expose it to our customers. In these domains, missing entities, relations, or operations just confuses and frustrates users and inevitably slows down our ability to improve our product. Working around these missing pieces even distorts the trajectory that our product takes over time.

But not everything has an obvious, prestatable algebra that relates it to the other entities in our products. In fact, our products as a whole relate in un-prestatable ways to other products, our customers' environments, and the rest of the world. They are part of a co-evolving, complex adaptive system, where interactions between parts constantly create novel niches and affordances that other parts can inhabit and make use of. It is not just that we don’t currently know how our product will need to evolve in this dynamic environment but it is likely even in principle impossible to know the specifics of how our product will need to adapt over time. Here, there is no absolute knowledge. The exact details of the way that these systems unfold are unknowable beforehand; they are computationally irreducible so the only way to know where you will end up is to play every step of the game between now and then.

But even for these aspects of our domains, even when the details of how our product needs to work in the future cannot be known, we need not completely give up design and abstraction.

We know more than we might think.

We know that our product will need to evolve and we know that interactions between concepts and parts of our systems create constraints that make it more difficult to evolve the system. We know that the more closely the relations between the components of our system match the relations between the concepts we know about in our domain, the more easily we will be able to model new domain concepts in our product.

Evolvability does not arise as a natural consequence of taking small steps or building sprint by sprint. Evolvability is not a property that derives from how something is built. Evolvability is a property of the built thing; it derives from the structure of the relations between the parts of our product and it can be explicitly designed into our products.

This is why understanding the deeper reasoning behind the agile maxims is important. If you happen to be working on a part of a product where the epistemic premises for working in an agile fashion are met, you are also working on a part of a product where the most important trait of your system is evolvability.

Many take these maxims to mean that we should just directly build concrete solutions for individual user stories, one after the other. Instead, we think the answer is to build an evolvable product, where the concepts you know about are properly represented (reified), with hard interfaces between components, and with abstractions introduced to keep interactions between components to a minimum. Abstraction and structure become more important when building evolvable systems, not less. If you leave a domain concept that you've uncovered un-represented in the product, it becomes harder to operate with agility, not easier.

Ruthlessly prioritize to maximize your rate of learning, not as an end in and of itself. Abstract as you learn and as the true nature of things is uncovered but not before. Consider whether there's a natural relation between the thing you're told you ain't gonna need and the rest of your product before you throw it away.

Why is this on our mind at Simply Stated these days?

Because every product we know of is composed of user flows. The user flow is the abstraction that ties together all of the parts of the product from the customer perspective. The user flow is one of the primary things that product teams work on and that customers experience.

And there are almost no product teams that can point to their user flow. There's almost never a place in the system that encodes the user flow. And that's a problem.

That's a problem that we're aiming to help fix.

Because the user flow is where the action is. That’s the part of your system whose details will evolve most rapidly, where agility commands the greatest premium.

We have no idea whether the specifics of particular steps of your user flow are in the knowable or unknowable category but we’re fairly certain that the coarse grain relationships between those steps is eminently knowable.

And we think that making user flows real and tangible will help all of us build more evolvable, adaptable products.

Stay tuned for more.

The storyteller makes no choice

Soon you will not hear his voice

His job is to shed light

And not to master

- Terrapin Station, Grateful Dead

f-of-xstate: run some logic on your logic

Adam Berger — Tue, 22 Nov 2022 15:33:23 +0000

Introducing f-of-xstate: free the insight and knowledge you worked so hard to build.

Every day as programmers and engineers, we write logic. If this, then that. When this, do that. Etc.

But with too few exceptions, we write that logic as text in a format that's so hard to glean real semantic meaning from that we've all probably taken at least one full undergraduate course about how to extract information from program text, transform it, and write it out again in a format more conducive to execution.

The closest most of us come to real, automated inspection or modification of logic tends to be in the form of macros or evals and the general advice on both counts is, most charitably, to use them as a last resort.

But does that really make sense?

We spend the vast majority of our time thinking about our program logic and then codifying all of that understanding about our problem domains, esoteric edge cases, and easy-to-miss implementation gotchas into a prison of text. And should we ever want to break free those gems of insight in the future, we will almost certainly need a human to read through everything we've written.

Our logic encodes some of the most important intellectual property we produce. It is the synthesis of everything we've learned. And we lock it up in text.

There is a better way.

We'd like to introduce f-of-xstate, our recently-open-sourced library for querying and modifying your app logic.

First of all, we can express our logic in statecharts. If you're working in javascript, XState is a great choice for writing and executing your app logic as a statechart. Just by moving your logic from text to datastructures, specifically statecharts, you'll already have gained clearer insight into your own understanding of your problem space.

Next, we can query the structure of our statechart to derive new meta-facts about our logic. This is where f-of-xstate comes in. We aim to make it easier to programmatically introspect your statecharts. We'll see an example below.

That's not all, we can also use f-of-xstate to easily modify our logic, layering on generic functionality or enforcing important invariants.

Show me the code!

Let's see an example of querying our logic. Let's imagine that we have some set of destructive actions that should always be guarded by user confirmation. In <20 lines of code, we can write a function that checks our logic to ensure that property holds. You could also imagine building something more involved like a tool to show users step-by-step instructions from wherever they are in your app to any goal state they want to reach.

Let's check out one more example. This time, instead of just detecting dangerous states, we'll fix them! Given any "dangerous" machine that might delete a user's data without confirmation, we'll convert it into a "safe" machine that always prompts for confirmation.

Head over to simplystated/f-of-xstate to see more examples (and star the repo for later).

Once in a while, you get shown the light

In the strangest of places if you look at it right

- Scarlet Begonias, Grateful Dead

Adam Berger Founder, Simply Stated

Engineering is tradeoffs... right?

Adam Berger — Wed, 16 Nov 2022 01:05:12 +0000

Efficient frontiers, problem structure, and how to reframe your way to a free lunch.

We always talk about tradeoffs. Strike up a conversation with most engineers about almost any problem they've worked on and you're likely to hear a lot about how they had to consider and choose from among various tradeoffs.

Living in a tradeoff-rich world, many of us start to assume that literally everything requires tradeoffs. Want better performance? Better sacrifice readability. Want quicker time to market? Get ready to give up reliability and correctness. Pareto improvements? Never!

...But does every improvement really require a sacrifice somewhere else?

The efficient frontier

Let's take a quick diversion into finance. Modern portfolio theory is based on the idea that every portfolio (basket of assets) has a volatility and expected return derived from the assets and their cross-correlations. The space of possible volatility/return pairs is constrained by the available assets and, in particular, their inter-relationships (correlations). That is, if you plot the volatility/return of all possible portfolios composed of some set of assets, you'll find a boundary you can't cross. At that boundary, called the efficient frontier, you can pick your tradeoff between risk and return but you can never construct a portfolio with a higher return and equivalent risk or lower risk and equivalent return to one on the efficient frontier. However, if you have a portfolio inside the efficient frontier, you can do strictly better--increase your return and keep the same level of volatility or reduce your volatility and keep your same return--by moving up or over to a point on the efficient frontier.

By User:G2010a - Own work, Public Domain

As an example, if your portfolio consists entirely of umbrella maker stock, you could probably achieve higher returns with lower risk by adding a few shares of an ice cream manufacturer. However, there is no combination of umbrella and ice cream stock that will get you 50% returns with 10% volatility--that is beyond the efficient frontier.

The efficient frontier... in engineering

So, how is this related to software and engineering?

First of all, we need to swap the x-axis from the above picture. In engineering, our axes represent limited quantities and we'll assume more is better but we tend to have a maximum achievable quantity on each axis. (Technically, we're now talking about Pareto Frontiers). For the rest of this article, imagine x and y axes labeled with quantities like: performance, readability, agility, ease of maintenance, scalability, engineering time, number of engineers, etc. such that more is "better."

Anyway, once you're on the efficient frontier, everything really is just tradeoffs. There is no free lunch. You must give up something to get more of something else.

But if you're inside the efficient frontier, you actually can do strictly better. You don't need to give up any x to get more y. You have a menu of tradeoff-free improvements to choose from.

So, is everything really just a matter of picking your poison and making the right sacrifices to hit a reasonable set of tradeoffs?

Probably not.

There is plenty of knowledge sharing and competition driving us all to find and adopt better and better ways to structure our systems but how sure are you that you're actually on the efficient frontier, that you've reached the best of all possible configurations such that nothing can possibly be improved without giving up something in return? Based on what we've seen in industry, that's just not very likely.

At the very least, whenever you're discussing a tradeoff you think you have to make, spend some time to really convince yourself that you're already on the efficient frontier, living in one of the best of all possible worlds.

But what if you decide you really are on the efficient frontier?

Surely, if you're on the efficient frontier (or the pareto front), then you must really have to choose, right?

Maybe.

But remember, the efficient frontier was determined by the interrelationships between the components of our system or, as I like to call it, by the structure of the system. In the portfolio theory case, the structure was governed by the correlations between assets. In our engineering case, the structure of the system is governed by the constraints of our problem space.

It's tough as a market participant to change asset correlations (and I'm fairly certain that the SEC looks unkindly on those who attempt it).

It's also tough but eminently possible as an engineer to change your conception of your problem space.

React did just that. Prior to React, we were all solving the problem of mutating the DOM in response to events and--wow!--that problem has a shallow efficient frontier. React reframed the problem to one of updating abstract state in response to events and generating a DOM based on that state and immediately pushed out the frontier of the possible.

The key insight here is that the same business problems can be approached by solving any one of many possible technical problems. The mapping from business problem to technical problem is many-to-many. But the choice of technical problem determines the structure of the technical domain, which determines the efficient frontier of what's possible.

Pushing out the efficient frontier by uncovering a new problem structure that subsumes a significant set of use cases of the current best alternative is no mean feat. These are the events in the history of programming we still talk about decades later and look back on the before times with astonishment: "they used to program like that?!?!" Time sharing, structured programming, OOP, functional programming, map/reduce, Docker, and React are all examples of structural reframings that changed the constraints engineers had to deal with in solving business problems. The big ones change the world. Plenty of small ones have changed industries, markets, and companies. Uncovering new structures, new relationships between components, is a worthwhile goal.

That was a fun history lesson. How do I actually put this to use?

When you're facing a problem and think you might need to make a tradeoff:

Really test whether you're on the efficient frontier of the problem space (i.e. set of constraints imposed by system structure) you're facing. If you're not, think hard to find a way to formulate your solution to avoid any sacrifices.
If you really are on the efficient frontier, spend some hammock time to think about how you might reframe the problem that your solving in such a way that the structure of the system (the relationships between its components) and the constraints that they imply push out the efficient frontier sufficiently far that you can easily achieve your goal without any sacrifices.
When all else fails, make a sacrifice, write it down, and keep it in the back of your mind in hopes that some flash of insight one day allows you to reframe the problem.

Aren't you into statecharts? What does all of this have to do with that?

At Simply Stated, we believe that statecharts represent a key reframing of the problem space of building apps. Whether you're looking at how product teams collaborate, how engineers implement solutions, how companies gain confidence that those solutions work, how customers learn to use them, or how those solutions can be safely adapted over time, we think statecharts and, more generally, declarative logic expand the set of achievable outcomes. We're tired of using (and, admittedly, building) software that doesn't work and takes hundreds of people too long to build. We think we can build better software faster with statecharts and declarative logic. That's why we want to contribute to the ecosystem of tooling needed to achieve mass adoption of this transformative reframing of the problem space facing engineers.

Since it cost a lot to win

And even more to lose

You and me bound to spend some time

Wondering what to choose

- The Deal, Grateful Dead

Follow @abrgBuilds and join the Simply Stated newsletter for more like this.

Original