Introduction
Fardjad Davari is a software engineer and architect with a passion for socio-technical systems and collaborative software design. He’s currently a software consultant with Xebia, and previously worked in the e-commerce domain.
We spoke with Fardjad to learn more about his journey, lessons learned, and advice on software architecture collaboration. With 15 years of experience in the industry, we were super excited to have him share his insights with the community.
Can you tell us a bit about yourself and your background?
My name is Fardjad Davari. I’m a software engineer and consultant with broad experience in software development, architecture, and technical leadership.
Video games and a lot of childhood curiosity got me into coding back in 1997, and I officially started my IT career in 2010. Over the years, I’ve worked across a variety of industries and helped organizations operate more efficiently at a larger scale by aligning teams and enabling them to design their software collaboratively and with intent.
How did you get into software architecture specifically?
It happened gradually and organically. As I gained more experience building software and working with IT organizations, I learned firsthand about the challenges of responding to changes quickly and sustainably. This led me to focus on helping organizations address these issues.
Can you give us a high-level overview of the different systems in your most recent role?
The company I worked with operated multiple distribution centers and hundreds of brick-and-mortar stores across the country. Those were mostly managed by third-party software systems, with a handful of custom-built adapters and components for core business processes.
The online shop, marketing automation, and fulfillment systems, on the other hand, were largely custom-built. These systems were responsible for 1. Encouraging customers to try new products, 2. helping them find and order what they needed, and 3. supporting drivers in delivering goods efficiently.
What tools did you use to document software architecture?
We had lots of diagrams made with drawing tools such as Draw.io (diagrams.net) and Excalidraw or diagram as code tools such as Mermaid and PlantUML. We also used the visualization capabilities of our APM tools to gain insights into what applications were connected to each other. Since early 2024, IcePanel became the source of truth for our architecture model. This enabled us to consolidate previously scattered diagrams into a unified model that everyone in the organization could access.
Most of the documents were stored in the knowledge base system (Confluence). Technical documentation and reports were often stored closer to the code and sometimes cross-published to the knowledge base for better discoverability.
How did you ensure documentation remained up to date with changes?
Maintaining a large number of hand-crafted documents and diagrams is especially challenging at scale. In many cases, solving these challenges at scale involves automation. Tools exist that can automatically detect and map connections between applications and resources, but they still fall short of capturing the intentions behind design decisions. Preserving the “why” behind the design decisions we make is context we care deeply about and don’t want to lose.
In the end, what worked for us included:
- Proactively removing outdated documentation. For instance, we tracked the amount of interactions with documents and eliminated those that hadn’t been used for a certain amount of time.
- Keeping the documentation (or the source of truth) close to where changes happened, such as in code repositories.
- Assigning a clear owner to each part of the system and making sure that updating the documentation was part of the daily workflow.
- Transitioning from scattered diagrams to a unified (C4) model.
What documentation standards did the team follow?
Since early 2024, all teams in the e-commerce domain started to maintain an (almost) always up-to-date model of the architecture in IcePanel. That helped teams understand the bigger picture and have more meaningful discussions and collaborations with each other. Around the same time we started adopting standardized formats for ADRs and RFCs to streamline the change process.
What are common mistakes you see when it comes to software architecture docs?
A common mistake I see in architecture diagrams and models is that they highlight the insignificant aspects of a design. As Grady Booch beautifully puts it:
“All architecture is design, but not all design is architecture. Architecture represents the significant design decisions that shape the form and function of a system, where significant is measured by the cost of change. Every software-intensive system has an architecture: some are intentional; a few are accidental; most are emergent. All meaningful architecture springs from a living, vibrant process of deliberation, design, and decision.”
A software architecture document should focus on the significant design decisions and provide enough context (for the intended audience) to explain why those decisions were made. Simply drawing a line between two objects in a diagram or stating that object A communicates with object B using a certain protocol doesn’t necessarily convey the significance of that part of the design.
How did you first come across the C4 model?
I first encountered the C4 model while researching diagram-as-code tools. I came across a talk Simon Brown gave at the “Agile on the Beach” conference in 2019.
What has been your experience like with the C4 model?
In my last assignment, training the teams in the organization to build a useful architecture model took some time and effort, but I think it was worth it.
After the initial learning phase, we saw people from both technical and non-technical backgrounds interacting with the model regularly. The use cases ranged from the 24/7 support team quickly identifying the right team to contact, to engineering managers analyzing dependencies, and developers collaborating more effectively through the model.
If there was anything that you’d change about the C4 model, what would it be?
This might be a common response, but I’d probably change the term “Container.” It’s an overloaded term and can be confusing, especially for people new to the C4 model.
What role did security play in the architecture?
The company had a dedicated security department, and engineers worked with them to ensure the design and implementation were secure. Having a unified architecture model that was accessible to everyone in the organization made it easier to receive feedback from many stakeholders, including those with security expertise. For sensitive areas such as payment processing or authentication systems, we ensured that architecture documents were reviewed and audited by security experts before implementing or making changes.
In what ways do you think the role of software architects will change in the next 5 years?
I’m not sure about the timeline, but I expect more companies to shift away from the traditional model where a chief architect makes all the decisions. Instead, we’ll see a more collaborative approach, with architects focusing on empowering and enabling teams to make intentional decisions about system design.
