We’ve designed and built the TrustYou CXP platform from scratch, making a bunch of architectural decisions along the way.
With multiple product teams and temporary teams working in parallel on interdependent subsystems, our engineers need a high level of autonomy to move fast. But autonomy without alignment leads to chaos. A solid strategy for growing an evolutionary architecture has been key to maintaining alignment while empowering autonomy.
“Architectural decision” is an umbrella term covering a wide range of choices in how we build software. In this article, I share a few thoughts on how we approach the architectural decisions on the structure of the software and the technology roadmap for the TrustYou CXP platform.
Architectural Decisions on Structure: Bounded Contexts
Bounded context is a key concept from Domain-Driven Design (DDD). You’ll find formal definitions in both the “red book” and the “blue book,” as well as many excellent articles and resources.
Bounded contexts have formed the foundation of our architectural decisions affecting the platform’s structure. We began by identifying the subsystems and defining bounded contexts for each of them.
Of course, our definitions include the ubiquitous language of the domain model—but we’ve focused even more on the inbound and outbound data and actions for each context.
We document our bounded contexts using a common template and keep them all together on a shared online board across Product & Engineering.
Because our focus is on the boundaries between subsystems and the details of their interfaces, defining the bounded contexts has been a collaborative effort. Engineers, team leads, and I have worked together to build a shared understanding of each bounded context, its boundaries, and its interfaces.
We held workshops with representatives from all product teams to answer key questions:
- What are the platform’s subsystems?
- What are the purpose and goals of each subsystem?
- What are the core entities and objects in each domain model?
- What’s the ubiquitous language for each?
- What are the inbound and outbound interfaces—data and actions—of each subsystem?
This top-down, workshop-based approach helps us avoid siloed thinking. It also allows us to uncover hidden assumptions early and make better decisions.
We use the levels 1 and 2 of C4 to document our system architecture. Once we defined our bounded contexts, they served as the main input for our System Context Diagram. This diagram captures subsystems, external dependencies and actors, and all interfaces—internal and external. It’s been a strong foundation for making engineering decisions at every scale.
Key ingredients? Collaboration, the right audience, and quality time for the workshops.
Architectural Decisions on Technology: Technology Roadmaps
Technology decisions have been just as important as structural ones in shaping the architecture of TrustYou CXP.
We use technology roadmaps to discuss and visualize which tools, techniques, and frameworks we’re adopting, phasing out, or evaluating. In fact, we have different technology roadmaps for different chapters in our department and each evolves independently.
While the ThoughtWorks Tech Radar is the most popular format out there, we’ve found Rogers’s technology adoption curve works better for us.
Our technology roadmap has six stages:
- Spot it
- Pilot it
- Engineer it
- Mine it
- Deprioritize it
- Decommission it
Each stage comes with guidelines to help clarify what it means to be there. These visuals and tips support meaningful discussions, help spot duplication, and surface knowledge-sharing opportunities.
When evaluating new technologies or comparing alternatives, we run pilots with clearly defined scopes and success criteria. The results are documented and support the final decision.
We created the first versions of these roadmaps before we even began implementing CXP—and now we aim to update them twice a year.
“Don’t You Write ADRs?”
TL;DR: Absolutely.
Yes, we write ADRs. Sometimes for decisions around bounded contexts and technology. But we also use ADRs for many other types of architectural decisions.
That said, we don’t force every single decision into an ADR. Our focus is on having the right conversations with the right people. When an ADR adds value to the discussion (and improves the decision), we write it. Sometimes, a decision is quick, made by a small group, and we jump straight into implementation.
Discuss, Visualize, Gather Feedback, Iterate
At the end of the day, it’s all about applying solid principles and best practices.
Architecture is something you grow with your platform—not something you define once and freeze forever. Make sure you explore alternatives. Surface the trade-offs. Get feedback from both technical and non-technical stakeholders. And most importantly, make conscious decisions.
Things will change. Start small, iterate, and avoid getting stuck in endless discussions aiming for a “bulletproof” solution. Spoiler: you won’t know what’s bulletproof two years from now.
Bounded contexts, technology roadmaps, and ADRs help us follow these principles—and maybe they’ll help you too.
