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.
Decomposing the standalone content updater into components
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:
- Scheduled Content Updater: This is a Spring scheduled task that is responsible for orchestrating the updating of content from Twitter, GitHub and news feeds using some connectors to fetch the data.
- Twitter Connector: This is the component that connects to Twitter using both the REST and streaming APIs. It's implemented using the twitter4j library.
- GitHub Connector: This is the component the connects to GitHub using GitHub API. It's implemented using the GitHub Java API that is a part of Eclipse Mylyn.
- News Feed Connector: This is the component that fetches blog posts and news via RSS/Atom feeds. It's implemented using the ROME library.
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.
UML component diagrams
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.