Documenting Software Architectures [#6]
A few years ago, I worked for a company that was building a web-based SaaS platform to replace the legacy applications it offered to its clients. After a few months, the architect's team started dissolving, and one by one started leaving the company for reasons I could never tell. Other engineers in the company took over some of the responsibilities that the team had. It was chaotic initially because each person who tried to take the leadership on this matter for the next months had a different background (Data engineers, frontend engineers, etc.). They were pushing in different directions; some didn't have much time in the company and were trying to solve design features that were already solved and working well.
It took some months until things got on the right path again. Part of the solution was forming a new architecture group that involved experienced engineers from different backgrounds, a mixture of people who had a long time in the company (they knew how their system works) and some fresh eyes. One of the keys was that this group discussed design challenges and the decisions we documented and shared across teams.
I remember giving this a lot of thought, and I will always wonder how much time and money it cost the company to lose the architects of this platform. Another question I had was how could companies, especially the ones where their core is software products, can prevent this. One of the conclusions I had was that software architecture is an asset, must be treated like that, and must be documented. Documentation must go beyond just diagrams; it must include how and why design decisions were made; otherwise, people taking over will wonder the why, how, and when of these decisions.
After this experience, I looked for formal education in this matter; a friend recommended a book called "Documenting Software Architectures.". After finishing it, I looked for similar books by the same author and realized there was a course based on the book and certification path to "SEI Software Architecture Professional" offered by the Software Engineering Institute of Carnegie Mellon. This is how my journey to document software architectures began.
Why is software architecture important?
- Software architecture is an asset of organizations; it can be transferred and reused. What can we reuse? We can reuse requirements, infrastructure, components, code, and experience.
- It is a communication tool. Teams can use it to transmit knowledge and discuss changes.
- It is a guideline for teams involved in software development, quality assurance, and maintenance.
-
It helps us achieve quality attributes (A quality attribute is a measurable or testable property of a system that is used to indicate how well the system satisfies the needs of its stakeholders), such as:
- Availability: Software property that indicates that a service is available when needed.
- Modifiability: Software property that indicates how easy it is to modify or introduce new features in a system.
- Testability: Software property that indicates how easy it's modules and features can be tested.
- Scalability: Software property that indicates how well the system adapts to meet demands.
- Security: It's the capacity of a system to protect data and information from non-authorized access.
- Usability: Software property that indicates how easy to perform a task is, and the support it gives to users.
- Performance: It's the capacity of a system to perform taks under a time box.
- Interoperability: It's the capacity of a system to exchange information with other systems in a particular context.
Why should software architecture be documented?
I hope the introduction I made at the beginning of this article has made a strong point on why documentation is necessary. I will expose some other important reasons here.
- Software architecture documentation can be used as educational material to onboard new teammates and develop new features and systems.
- It can be used as a tool for analysis. For example, it can be helpful when a request to improve a quality attribute such as performance or scalability is requested.
- It can be used as a guideline for developers, people in charge of deployments, and QAs.
How can we document a software architecture?
Architects and developers love to make diagrams on whiteboards, papers, and digital tools when designing a system. Many times that is how the design phase starts. If we are designing enterprise applications, the diagram will probably have some software components that run in a server, web APIs, and clients such as mobile or web applications. These diagrams are good; they help us to reason about the components, relations, and quality attributes we want to achieve. That can't be all, right?
Systems are too complex to be represented in a single diagram. Especially nowadays that cloud computing is more accessible, and we have microservices, gateways, GRPC, Web APIs, etc. Views & Beyond is an approach to document software architecture that is based on the concept that there are different views and angles to describe a system.
A system is designed using different types of structures, and structures are documented using views of these structures. Structures are separated into three categories: Component & Connector structures, Module structures, and Allocation structures.
As I mentioned, Views are used to document structures. A View is the representation of different elements of the system and is more than a diagram. It is usually composed of:
- A primary representation using a diagram (The notation could be ADLs, UML, informal notation, etc.).
- A catalog of elements where the main elements are described, including responsibilities and properties.
- Reasoning that led to the design decisions.
Views & Beyond: Structures & views
Component & Connector Structures
These types of structures let us desing the system from a runtime perspective (In this type of structure, elements have a runtime behavior). Describes the relationships between the software elements (Components) and how they will interact (connectors).
Component & Connector structures can be used to:
- Reason about how data flows through the element and connectors of the system.
- Identify parallelism opportunities.
- Identify main data stores.
- Identify what parts of the system need replication.
These are some common Component & Connector views:
- Call-Return views such as Client-Server, Peer-to-peer, Service-Oriented Architecture
- Event-Based views such as Publish-Subscribe
- Repository Views such as Shared-Data
Module Structures
These types of structures let us design the system from the perspective of static elements (In this case, we call these elements modules, and modules are units of implementation).
Module Structures can be used to:
- Identify the responsibilities of each module.
- Identify the dependencies of each module.
- Impact analysis.
- Reason about quality attributes such as modifiability, portability, and reuse.
- Provide a guide for construction
These are some common Module Views are:
- Decomposition Style
- Layered Style
- Data Model
Allocation Structures
These structures let us make decisions regarding software elements and their relation with external elements used to run or create the software. The elements in these structures are:
- Software elements
- Organization units: a person, a team, a department.
Allocation structures help us reason about:
- Resource assignment
- Assignment of responsibilities
- Provide information about the structure of the project to new members
Some common Allocation Views are:
- Deployment views
- Implementation views
- Work Assignment views