Documenting Software Architecture

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

We learn how to code and we build some cool applications, and then we learn about architecture and how to make the application maintainable for several years…

However when we need to explain to someone else (new developer, product owner, investor, …) how the application works, we need something more… we need documentation.

But what documentation options do we have that can express the whole application building blocks and how it works?!

In this post I’m going to write about:

  • UML
  • 4+1 Architectural view model
  • Architecture Decision Records
  • The C4 Model
  • Dependency diagrams
  • Application Map
Continue reading “Documenting Software Architecture”
Advertisements

Reflecting architecture and domain in code

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

When creating an application, the easy part is to build something that works. To build something that has performance despite handling a massive load of data, that is a bit more difficult. But the greatest challenge is to build an application that is actually maintainable for many years (10, 20, 100 years).

Most companies where I worked have a history of rebuilding their applications every 3 to 5 years, some even 2 years. This has extremely high costs, it has a major impact on how successful the application is, and therefore how successful the company is, besides being extremely frustrating for developers to work with a messy code base, and making them want to leave the company. A serious company, with a long-term vision, cannot afford any of it, not the financial loss, not the time loss, not the reputation loss, not the client loss, not the talent loss.

Reflecting the architecture and domain in the codebase is fundamental to the maintainability of an application, and therefore crucial in preventing all those nasty problems.

Explicit Architecture is how I rationalise a set of principles and practices advocated by developers far more experienced than me and how I organise a code base to make it reflect and communicate the architecture and domain of the project.

In my previous post, I talked about how I put all those ideas together and presented some infographics and UMLish diagrams to try to create some kind of a concept map of how I think of it.

However, how do we actually put it to practice in our codebase?!

In this post, I will talk about how I reflect the architecture and the domain of a project in the code and will propose a generic structure that I think that can help us plan for maintainability.

Continue reading “Reflecting architecture and domain in code”

Action-Domain-Responder

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned about Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

MVC was created in 1979, in a context of desktop applications with CLI user interfaces and it implied that the UI would be changed automatically if there were changes in the database, caused by some factor external to the user. The same pattern was perfectly usable later on desktop applications with a GUI.

However, its usage in web applications has always been an adaptation because most web applications don’t change the UI as a consequence of changes that happen in the server side, there is always a call from the UI asking the server side for an update of the screen.

I have talked about variants of the MVC pattern before, this post is about another variant: Action-Domain-Responder, created by Paul M. Jones. Continue reading “Action-Domain-Responder”

Resource-Method-Representation

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned about Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

MVC was created in 1979, in a context of desktop applications with CLI user interfaces and it implied that the UI would be changed automatically if there were changes in the database, caused by some factor external to the user. The same pattern was perfectly usable later on desktop applications with a GUI.

However, its usage in web applications has always been an adaptation because most web applications don’t change the UI as a consequence of changes that happen in the server side, there is always a call from the UI asking the server side for an update of the screen.

I have talked about variants of the MVC pattern before, this post is about another variant: Resource-Method-Representation.

I feel the need to talk about it, not because I find it a key pattern in my practice but because of the misconception that it is the same as the ADR pattern, of which I will write about soon. Continue reading “Resource-Method-Representation”

“Model 1” & “Model 2”

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned about Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

Java Server Pages (JSP) is a technology, a scripting language comparable to PHP, ASP, or even Python, that is used to create server-side pages interpreted by the JVM and which can use Java objects.

The first JSP specifications, published in 1998 by Sun Microsystems, defined two ways of structuring an application so that the presentation logic would be decoupled from the business logic, and even the use cases, in an HTTP request/response paradigm.

Some consider these “Model 1” and “Model 2” the first tries at adapting the MVC pattern, originally intended for a context of desktop software development, to the web HTTP request/response paradigm. Continue reading ““Model 1” & “Model 2””

More than concentric layers

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

In my previous post in this series, I published an infographic that reflects the mental map I use to figure out the relationships between the code units types.

However, there was something that I always felt it was not very well reflected there, but I just didn’t know how to do it any better: the shared kernel.

Furthermore, I figured out a few more things, and I’m gonna write about it all in this post!

Continue reading “More than concentric layers”

Deployments with containers

This post is part of The Containerization Chronicles, a series of posts about Containerization. In them, I write about my experiments and what I’ve learned on Containerization of applications. The contents of this post might make more sense if you read the previous posts in this series.

Now that we have the project integrated with a Continuous Integration server, where we run the tests and report back to GitHub pull requests with the results of the test run and the coverage, we can deploy our project and make it available on the Internet.

We will do so with Heroku. I have chosen Heroku because it allows me to perform these experiments for free.

If you want to jump into the code, this is the tag for this post.

Continue reading “Deployments with containers”