What is an ADR?
An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences. ADRs help teams document the reasoning behind architectural choices, making it easier to understand decisions in the future and onboard new team members.
Structure
We are following a specific template called Y-Statement. It has this structure:
_15### Record title - 0000/00/00_15_15**In the context**: The situation or problem that requires a decision_15_15**facing**: The specific challenge or requirement that needs to be addressed_15_15**we decided**: The chosen solution or approach_15_15**and against**: Alternative options that were considered but not chosen_15_15**to achieve**: The benefits and goals this decision helps accomplish_15_15**because**: Additional justifications gained during the decision making_15_15**accepting that**: The trade-offs, drawbacks, or consequences of this decision
It ensures that architectural decisions are well-documented, justified, and can be revisited or challenged when circumstances change.
An error occurred while loading the image decision-graph.webp
Records
Jest as test framework - 2025/09/10
In the context of creating a new username login app with a short deadline,
facing the need to maintain delivery confidence,
we decided to use the Jest Framework
and against using other test frameworks like ViTest or vtex-test-tools
to achieve regression testing,
because it is the framework that the team has the most confidence using,
accepting that writing comprehensive tests will increase our initial development time, and Jest may not be the most performant testing framework available
Custom State Machine as solution for state machine - 2025/09/10
In the context of creating a new username login app with a short deadline,
facing the need to manage complex authentication flows and state transitions,
we decided to use a Custom State Machine library for state machine implementation
and against using state machine libraries like Robot or XState
to achieve predictable state management and simple handling of complex authentication scenarios,
because it is lightweight and simple to understand, also the XState recent implementations don't work with IO env,
accepting that unfortunaly we will not have the machine visualizer and may this custom library introduce extra complexity in the project
VTEX Styleguide as design system - 2025/09/11
In the context of creating a new username login app with a short deadline,
facing the need to increase the delivery time,
we decided to use the VTEX Styleguide
and against create custom components or using other libraries like Faststore UI and Shoreline
to achieve faster interface development
because it is already used into other IO apps and the company has existing expertise in customizing it
accepting that this design system is outdated and may have some bugs