Streamlining Architecture Decisions at Procore
At Procore, we strive to have decisions made at the appropriate level, rather than being a strictly top down organization. We also need to ensure good decisions are made, which means they are based on solid engineering principles, take cross-functional considerations into account, and we remain consistent across teams. We also need to ensure that decisions can be easily reviewed by stakeholders.
Procore creates an Architectural Decision Record (ADR) document to capture our thoughts around major technical decisions to ensure future contributors understand the context and mindset behind each architectural and technical decision. This way, we can remain agile while keeping the process of architectural decisions clear and intentional.
Key Concept: What is an ADR?
An architectural decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences.
from https://github.com/joelparkerhenderson/architecture_decision_record
The value of our ADR is in the spirited discussion that it drives during the drafting phase, the review, and the evangelization of the document and to ensure that the problem has been duly considered, both when it comes to future benefits and potential risks.
We use Github as the repository to foster communication across the organization and enable discoverability. We easily track history, make modifications, and leverage Pull Requests as a review and collaboration process.
Our ADR structure includes:
- Title and number
- Date of creation
- Authors - one or more team members owning the area of responsibility with input from stakeholders
- Status
- proposed during review
- approved or accepted once agreement has been reached
- deprecated or superseded if no longer relevant. When superseded, the superseding ADR should also be referenced
It also contains the following three sections, which are the meaty parts of the record:
- Context
- Decision
- Consequences
Context captures details around the state of our internal systems, the ecosystem, or patterns being discussed, and larger architectural directions. Details to discuss here include:
- high-level architectural requirements
- initiatives or pressures involved in the decision
- assumptions that the team is operating under
- background on the alternative solutions
- historical ADRs or decisions that influence the current ADR
- glossary of terms
The Decision section includes the many solutions that were considered before finally selecting and proposing the optimal solution. This invites discussion into the tools and can help avoid the age-old question, “Did you consider...?”
Consequences addresses technical debt, performance, design compromises or areas of concern that may cause issues in the future or are not in scope for the ADR. The pros and cons that were deliberated on for the Decision and alternatives are also included here.
Finally, a review by Engineers and Architects ensures that the decision aligns with Procore’s architectural strategy. For example, during a recent Observability ADR review, we decided that the ADR in question covered Telemetry more than Observability. We decided to define the differences between Telemetry and Observability and split them into separate ADRs. The cross functional team review led to a better discussion on the contents of the ADR, provoked a deeper discussion on how to partition Telemetry and Observability work, and provided the additional benefit of attention to our new Observability team!
In conclusion, the ADR at Procore is one of our most important architectural tools for ensuring high quality in our Engineering wide decisions. The ADR process has helped streamline decision making at Procore as we grow, while maintaining the autonomy we value. If this kind of autonomy appeals to you, come join us!