Designing Anvil: Composable components
When solving challenges like paperwork, its best to break larger problems into smaller, digestible problems that can be solved individually. In designing Anvil, we focused on the structure of each solution so that they can be easily composed to solve any kind of complex paperwork.
When we set out to build Anvil, the premise seemed simple enough. Build an online tool to “convert PDF forms into online forms”. The vision was to enable anyone to create a TurboTax-like experience for the everyday paperwork that powers their business. Once created, the online form, or Workflow in the Anvil lexicon, would enable our customers to serve their customers with a modern online experience, coding not required.
As we peeled back the intricacies of paperwork, it became apparent that the simple mental model of paperwork was rarely the case in reality. The challenges start at the most basic level, the underlying technology of PDFs. PDFs are pretty difficult to work with as a developer because it’s a file format that prioritizes consistency of rendering and is intended for consumption (think ebooks, magazines, etc). Thus the PDF spec is oriented around drawing and graphics, making it even more difficult to use as a medium for data transfer (which is the main purpose of paperwork)!
Then there are the countless business rules: fill out this form if X, do this if Y, mix in some math, and require a specific form order. The IRS is most guilty of this. Every IRS form comes with an equally long set of instructions that require a professional to understand. I guess it makes sense as to why TurboTax flourished.
Finally, there are the undocumented rules; knowledge that lives in the heads of industry experts and is transferred through word of mouth or learned through trial and error over the years. In insurance, there is a customary way that some forms get completed. This “way” is poorly documented, despite there being an industry consortium that has standardized the paperwork. On top of that, the interpretation of rules changes how forms are completed. As a result, the underlying forms are not always adapted and instead are just co-opted for a new process.
With each new challenge, we had to rethink the atomic units of Anvil. Clearly a Workflow needed to be broken into 3 logical parts:
- the webform
- the PDF template
- the mapping configuration from webform to PDF
But each of these logical bundles contain countless sub-atomic units that together make up the larger logical units.
Anvil needed to create our own universe of rules and atomic units that can be composed to address any kind of paperwork and process. We needed to create the software lego pieces of Anvil, each piece governed by the rules of their “connectors” (the size and orientation of the little “studs” on each lego piece).
Webforms are composed of web components that are all descendents of the “basic text” field. For example, there are Name fields which have three basic text fields for First, Middle initial and Last name and also Address fields that are composed of four fields: street, city, state, zip, and so on.
Within each component we have modifications that determine the shape of the connectors and allow us to adapt each field to a specific need. We have:
- Integrations - i.e. Google Maps for address fields
With these pieces we can define and compose any kind of web-based input field.
The structure of PDF templates is dictated by the underlying PDF file format. PDFs are definitionally a coordinate-based system and everything needed to render a PDF, like fonts, is embedded in the file.
The goal of the PDF is to maintain consistency in how the PDF is rendered on any device and any platform, so the file itself needs to be “self-contained” and not reliant on things outside of the file beyond the rendering program. As such, Anvil’s PDF system needs the following basic units:
- Boxes with four x,y coordinates denoting the bounds
- Reference to the underlying PDF file
We then add in our own flavor of modifications to define the “connectors” for higher order lego pieces known as Field Types:
- Children fields - radio group is composed of two or more checkboxes
With these pieces, we can place text or images on a PDF based on the correct coordinates, align the text within the boxes, and also arrange the text in a conventional format, like (xxx) xxx-xxxx for U.S. phone numbers.
The mapping is perhaps the most important piece for bridging the gap between the old world of PDF paperwork and the new world of webform-based paperwork. Mappings allow us to take the modern online experience we all expect and superimpose it on the traditional paperwork process that makes the world turn. Here, the basic unit is a grouping of a webform input to a PDF output. The key is to allow for the grouping to be many-to-many, so many webforms can be used to populate many PDF forms.
The three types above (webforms, PDF templates, and mapping) make up the basic lego blocks of Anvil, but how they interact and work is defined by modifiers. Modifiers in Anvil allow us to change and define the rules of each component in order to make higher level components that hide away complexity. Modifiers in Anvil are extremely powerful, allowing you to transform the fields by:
- modifying the data - i.e. add two fields and use the result to pre-populate another field
- providing boundaries on the data and validate that the data is structured correctly
- presentation - only show a webform field if a condition is met.
Modifiers are the rules that define the connectors. Together, they define how each piece can be composed together into a Workflow.
Anvil components are thoughtfully designed and work together seamlessly. By designing each component with the intention of composability, we can guarantee that an Anvil Workflow will be easier to build, more reliable and have higher performance than “gluing” together disparate solutions from multiple vendors.
To the developers reading this, the above structure should be very familiar. It follows the principles in Object Oriented Programming, or the breaking of problems into smaller logical problems that can then be composed together like Lego pieces that can be composed to create something way cooler.
The previous sections also describe the concept of APIs. Each component has a defined interface and as long as the interface remains consistent through various iterations, the underlying component can change implementation without breaking the system as a whole.
These two concepts that permeate through Anvil’s technical design are what make Anvil so powerful, especially to other technology companies that can build upon our solution.
When building something new, it’s important to consider the system in which this new thing will live. Being thoughtful of our choices when designing the system can reap benefits down the road. Well-designed components mean you can build on top of a solid foundation, not a house of cards. It also means you can be flexible and pivot your product to meet customer requests. Today, Anvil offers two distinct product lines that directly benefit from being built on the same foundation. There are the individual APIs for developers and technology companies and the Anvil-hosted no-code Workflows for everyone else. Each product shares the same underlying system that empowers us (and hopefully you) to build something greater.
Questions? email us firstname.lastname@example.org thing here