Bernie on IT

I recommend the C4 model for anyone interested in IT architecture, from beginner to expert. I feel it has just the right amount of architecture to represent the IT system you are trying to describe. It doesn't burdened you with creating too many artifacts. You don't have to learn a lot of rules (e.g. which arrow to use for different forms of relationship). The C4 model lets' you focus on what's essential to communicate to others and avoid debates about nomenclature. You can represent your IT architectures at all levels, from conceptual to physical, which means you can use it through the entire lifecycle of your IT system. In addition, you can represent your architecture with many different diagrams, from system context diagrams to deployment diagrams. And while it's meant for software architects, it is suitable for any IT architect.

Another nice thing about the C4 model diagrams is that they are supported with PlantUML. That allows you to have your diagrams as code. I love that. Each time you diagram your architecture using PlantUML, you can push your .puml (PlantUML) files into a source code repository. A repository like github gives you greater traceability and accountability. You could have each change be a pull request that can be reviewed and approved before being accepted. And each change can come with a reason for why the architecture is changing (e.g., new requirement, constraint or architectural decision). The result is better architectures and better IT Systems.

"Defining and addressing the nonfunctional requirements (NFRs) for a system are among the most important of a software architect’s responsibilities. NFRs are the system quality attributes for a system, as distinct from the functional requirements, which detail a system’s business features and capabilities. Examples of NFRs include key concepts such as reliability, performance, scalability, and security. NFRs are cross-cutting in nature and affect multiple aspects of a system’s architecture. It's important to articulate and address the NFRs early in the project lifecycle and to keep them under review as the system is produced. To help with that task, you can use the following checklist of key NFRs. The checklist designed to be consulted when you define and evolve a system’s architecture."

The above quote comes from this piece (Nonfunctional requirements: A checklist – IBM Cloud Architecture Center). The bold text in it is key. NFRs describe the qualities your system should have. You have functional requirements and you have quality requirements (i.e. , NFRs). Any system design needs to address both.

The number of specified NFRs your system can have may seem endless but three of the key ones found at the top of any list are:

Availability and resilience

Performance and scalability

Security

Those three are typically covered in any system design I work on. The piece above has a great rundown on the various NFRs you'd expect to address in most system architectures. That said, they miss three NFRs that I think are important and that I would ask you to consider. The three are:

Accuracy

Maintainability (related to complexity)

Cost

There is often a tradeoff with accuracy and other NFRs, such as performance. To gain better performance, data will often be cached and served up even when it is out of date (i.e., inaccurate). That may be fine. But accuracy should always be taken into account and not just assumed.

Maintainability is often ignored, but it is key for the long term success of a system. Two examples of this. One, developers will sometimes not externalize values in their code; changes to the code require a fix and an outage. That is less maintainable than code with external values in a simple text file that can be changed on the fly. Two, code that is not well documented and not peer reviewed will be harder to maintain. Externalization, code reviews and documentation are examples of maintainability requirements you may have and should have for your IT system.

Cost is an important NFR because it causes tradeoffs with most other NFRs. For example, without cost considerations, stakeholders might have availability requirements that are for 99.99999….. It's only when cost (and complexity and maintainability) become factors do we see often see availability (and other NFRs) scale back.

Finally, NFRs are not just for software architects: they are for everyone. In fact, I wish the term "non-functional requirement" was replaced with "quality requirement". However I suspect software architects -- for whom functional requirements are key -- came up with that term, so we all have to live with it. When you think of NFRs, think Quality Requirements. Everyone involved in the design of an IT system wants it to have good quality. Understanding the NFRs/QRs are key to this.

One thing I like about system context / use case diagrams is that they help me define and uncover scope for an IT system. To see what I mean, let's say I was called in to help understand or build an IT system that has a touchscreen device like this:

A preliminary system context model (with an underlying use case) would look like this:

Pretty simple. But not the whole context. Let's dig further.

For any information that a user reads in an IT system, there is an implicit create information use case that has to exist. There may also be an update information and delete information use case (think C.R.U.D.), but there is definitely a create information use case.

Now in this example, the shopper is not creating items to search for. There must be another actor who is doing that. The person responsible for this IT system says that an Admin person does that. The diagram expands to something like this:

We may wonder if each item is added individually, or if there is a process to automatically add items. Through interviews we find out there is an inventory system that transmits information to our IT system and adds items to it overnight. Now our system context looks like this:

In conclusion, by asking questions about the information our initial user ("Shopper") is searching for, we find our scope has expanded to include two new users/actors: an Admin and an Inventory System. The scope of our new IT system is now better understood.

I'll confess: I used to struggle with the best way to represent user requirements for IT system I was designing. I finally found an approach that helped me alot, and that is defining the use cases in terms of CRUD.

An example of that is here. The diagram below represents four use cases. The Information User has four requirements for the system: Create, Read , Update, and Delete Customer Information. (I.e. C.R.U.D. the customer information. )

I found this simplified approach most helpful in defining what the user of the IT system wants. They want to do one of those four things to the information associated with your system, even if they say it differently.

If you look at other use case diagrams, you can often translate them in terms of CRUD. For example:

- get bank balance = read customer bank balance information

- book a flight = create flight booking information for a customer

- change customer address = update customer personal information

- cancel my order = delete customer order information

In each case, something is happening with information. And that something is CRUD.

One of the benefits to this approach as an architect: I know what the user expects for any request they send to the IT system. That in turn makes it easier to design the components that make up the system.

For more on this, see this

If you think of deployment diagrams at all, you might think of something like this:

Yep, most of the time, when you see examples of deployment diagrams, they feature very old technology. (e.g., The Sun Fire servers in the above diagram were around in the 2000-2010 period.)

These days, when IT architects draw their solutions, they are more likely to be cloud centric and look like this:

While this is an IBM Cloud example, all the major cloud service providers have reference architectures that look like this.

In my opinion, the second diagram is also a deployment diagram. It doesn't follow the UML format, but it is essentially showing where services and other technology are deployed and how they relate to each other.

What I want to argue for is that these new diagrams could take a few things from the old deployment diagrams. For example, in the new diagram, we see a number of services running in a Kubernetes cluster. If this was a traditional deployment diagram, it might show nesting of boxes that would be something like this:

Kubernetes cluster > Worker node > Pod

Or it could be even more specific, and state what version of Kubernetes is being used in the cluster, how many worker nodes there are, what is the capacity of the worker node, and what is the OS of the pod. You could also state within the pod what containers are running there.

To extend this approach further, the new diagram could show which application components the containers are manifestations of. It’s here where the deployment diagram provides value, for it’s here where you see the linkage between the application and the runtime environment. You could even have tag or other information. For example you could have one pod manifesting one version of application components and another pod manifesting a different version. That linkage from the software components being designed by the application architect and the cloud infrastructure being designed by the cloud architect can be very powerful.

What I sometimes see is the application architect will design the software independently of how it will be deployed. They will provide the cloud architect with needs the application has for specific services. From there, the cloud architect will work to build out the cloud infrastructure.

What I would prefer to see is the application and cloud architects working together to determine how the code should be deployed, and then working together to come up with the right deployment model. The properties of deployment diagrams are suited for making that collaboration and communication more effective.

This is another diagram I like because it shows the relationship between system context diagrams and use case diagrams:

If you were to simplify this diagram by making the Bank ATM a black box and just having one line from each of the actors (customer, ATM tech and Bank), you have a system context diagram. One of the many things I love about system context diagrams is the ability to do this: you start off with showing the relationships between actors and your new system, and from there, it is straightforward to showing the key use cases of your system.

I want to write more about system context diagrams. This is one of the reasons I think it one of my favorite ways to understand a system, new or existing.

I like this photo because it shows how package diagrams tie into deployment diagrams:

Sometimes you may wonder at work: am I creating any value? What if I told you that you create a tremendous amount of value every day. For example, when you learn a new skill, you create value in many ways. You create value for who you are currently working for (eg you build a new piece of software). You create value for others too. You create value for yourself (eg you learn how to write the software). You create value for future clients (eg they want you to write similar software for them). And you create value for your employer (eg they can sell your services to others). You create value for non work people too. Because you are marketable with your new skill, you can make money. That money can go to others, from loved ones to merchants.