Document your software architecture

Every application is born from an architecture, it can be pre-designed or a result of an implementation, regardless it's an architecture that if we ask many people what it is we'll find different, let's say "interpretation" of the word : blueprint, plan, backbone of a product, conceptual model, big picture and so on ... The bottom idea is we all agree that architecture is about understanding what we want to build, creating a vision or a clear view for building it and calling the right design decisions.

To clarify things these are "Types" of architectures: Network, Infrastructure, Security, Hardware, System, Database, Process, Software, Data ...

Software Architecture

As Simon Brown mentioned in his talk and his book "Software Architecture for Developers" I'll borrow his words

"software architecture is simply the combination of application and system architecture. In other words, it’s anything and everything related to the significant elements of a software system; from the structure and foundations of the code through to the successful deployment of that code into a live environment.

When we’re thinking about software development as software developers, most of our focus is placed on the code. Here, we’re thinking about things like object oriented principles, classes, interfaces, inversion of control, refactoring, automated unit testing, clean code and the countless other technical practices that help us build better software. If your team consists of people who are only thinking about this, then who is thinking about the other stuff?

? Cross-cutting concerns such as logging and exception handling.

? Security; including authentication, authorisation and confidentiality of sensitive data.

? Performance, scalability, availability and other quality attributes.

? Audit and other regulatory requirements.

? Real-world constraints of the environment.

? Interoperability/integration with other software systems.

? Operational, support and maintenance requirements.

? Consistency of structure and approach to solving problems/implementing features across the codebase.

? Evaluating that the foundations you’re building will allow you to deliver what you set out to deliver.

Sometimes you need to step back, away from the code and away from your development tools. This doesn’t mean that the lower-level detail isn’t important because working software is ultimately about delivering working code. No, the detail is equally as important, but the big picture is about having a holistic view across your software to ensure that your code is working toward your overall vision rather than against it."

What's this article about

That being said, the goal for this article is not going philosophical or start a debate, but rather make a guide for the lost developers out there to stop failing at communicating the software development process, especially documenting the software developement lifecycle.

Sketches

Sketching here is not about detailed modelling, comprehensive UML models or model-driven development. This is about effectively and efficiently communicating the software architecture of the software that we're trying to build through one or more simple sketches. This allows us to help everybody understand the Big Picture of what is being built, create a shared vision of what we’re building within the development team, provide a focal point for the development team, provide a point of focus for those technical conversations about how new features should be implemented, provide a map that can be used by software developers to navigate the source code and last and not least provide a starting point for techniques such as risk-storming.

here are some examples of sketches

If we search in google abour software architecture models or diagrams this what you'll probably find

C4 (context, containers, components and classes)

C4 represented by Simon Brown in his talk at the NDC conference 2017

"Assuming an OO programming language, the way that I like to think about structure is as follows … a software system is made up of a number of containers, which themselves are made up of a number of components, which in turn are implemented by one or more classes. It’s a simple hierarchy of logical building blocks that can be used to model most software systems."

We only know, sadly, that the code doesn't always say the whole story for the people to know, in the absence of documentation, in this situation we try to choose a number of simple diagrams of a certain level of abstraction instead of a single rather complex diagram.

Introducing the C4 :

1. Context: A high-level diagram that sets the scene; including key system dependencies and actors.

2. Container: A container diagram shows the high-level technology choices, how responsibilities are distributed across them and how the containers communicate.

3. Component: For each container, a component diagram lets you see the key logical components and their relationships.

4. Classes: This is an optional level of detail and I will draw a small number of high-level UML class diagrams if I want to explain how a particular pattern or component will be (or has been) implemented. The factors that prompt me to draw class diagrams for parts of the software system include the complexity of the software plus the size and experience of the team. Any UML diagrams that I do draw tend to be sketches rather than comprehensive models

~@author KK~

For the hungry readers :

Simon Brown's book Software Architecture for Developers or you can watch the conference https://www.youtube.com/watch?v=Ym9nhVZs89o

6min read medium article https://medium.com/geekculture/how-to-document-software-architecture-665db2842472

for more on C4 model : https://c4model.com/