As a follow-up to my recent post called Aligning software architecture and code, this is the third in a series of short posts that will look at the code behind the techtribes.je website that I recently open sourced on GitHub. The posts will also show examples of some simple software architecture diagrams based upon the C4 approach (context, containers, components and classes) that is described in my Leanpub e-book called Software Architecture for Developers. There's also a short introduction on InfoQ called Agile Software Architecture Sketches and NoUML. Part 1 can be found at techtribes.je - context and part 2 can be found at techtribes.je - containers.
As illustrated by the containers diagram, techtribes.je includes a standalone process that pulls in content from Twitter, GitHub and blogs. The following diagram shows the high-level internal structure of the content updater in terms of components.
In addition to a number of core components (described below), the content updater is made up of four components:
In my blog post called Mapping software architecture to code, I said that architecture diagrams should present abstractions of the code rather than some other conceptual or idealistic representation. In other words, if your architecture diagram is showing components, I should be able to find those components in your codebase. If those components *don't* exist in your codebase, you're misleading people about the structure of your software. To illustrate what I mean, if you take a look at the code for the content updater, you'll see that it *is* made up of the four components that you see on the diagram.
For completeness, here's a diagram illustrating the core components.
Again, a look at the code will show that these components do exist. I've taken a "package by component" approach to structuring the codebase and that's why the diagram shows components. If you're packaging your code by layer or by feature, your diagram should reflect this. I'll talk more about this topic in the next post.
As a final note, these component diagrams could have been drawn using the UML component representation and the corresponding diagram. And this raises the question of why I've not done this. In my experience, the UML component notation seems to confuse people, perhaps that's because you can use several variations to do the same thing. Also, I'm not sure that the notation adds much. For me, regardless of notation, the important thing is that each diagram tries to show a single and consistent level of abstraction.
The next post will show some of the implementation details.
Simon is an independent consultant specializing in software architecture, and the author of Software Architecture for Developers (a developer-friendly guide to software architecture, technical leadership and the balance with agility). He’s also the creator of the C4 software architecture model and the founder of Structurizr, which is a collection of open source and commercial tooling to help software teams visualise, document and explore their software architecture.