Documenting Your Product – Part 6 – System Components
This is the sixth and final post in a series about documenting technology product builds. If you missed the intro, Part 1 – Use Cases, Part 2 – Requirements, Part 3 – Sequence Diagrams, Part 4 – Data Models, or Part 5 – Sharing and Collaboration go check them out. At the end of this series, I’ll be providing a bunch of templates and resources to make this process more manageable.
For this series, we’re building a product called PetSitPro, which matches pet sitters with pets in need of pet sitting. As a refresher, a Pet Sitter is someone who provides pet care, and a Pet Parent is someone who has a pet to take care of.
In this post we’re going to talk about how you model out system components. Why is this skill critical, even if you’re not a “engineer”? The main reason is that system component drawings help you to understand the complexity you’re creating in a way that words can’t. Even if they’re basic block diagrams, if you’re able to think through how each of your components talks to the others, it helps you to understand how complex the product you’re trying to build might become. Complexity is the breeding ground for hemorrhaging cash. Let’s dig in.
What Are System Components?
I could be witty and say something like “System components are the components of the system”, but I won’t. Let’s talk about the different kinds of components first:
- Infrastructure – Things like your application hosting environment, where you have firewalls, application servers, connections to the network and so on. You might also include things like load balancers, databases, and a host of other things. A great tool for building / creating infrastructure diagrams especially for Amazon Web Services (AWS) is CloudCraft. Click on over to their home page and you can see some great examples of infrastructure diagrams.
- Application – This is where you’ll spend most of your time, as these are the components of your particular application. Application components are all of the building blocks that make your application what it is. I like using tools like Omnigraffle and Visio, but you can also do this work in Google Drawings (which is what we’ll use for our diagrams). Here’s a likely incomplete list of all of the components of the PetSitPro application:
- Web user interface
- Mobile application user interface
- Application API
- Authorization partner (Google, Facebook, etc.)
- Billing and charging system
- Payments Gateway (could be a part of billing but not necessarily)
- Ratings system
- Comments system
- Pet Sitters system
- Pet Parents system
- Scheduling system
- Order management system
- and so on…
That’s great, but we came here to learn how to draw, not read a bunch of stuff. But it’s important to realize that for what feels like a relatively simple app we’ve got a lot of stuff to build. This is why we spend time getting our thoughts out on paper, so to speak.
Basic Drawings Examples
Here’s a quick drawing of how we might first assemble our system components:
Pretty boring right? Everything’s the same color, etc. But even with this simple diagram we start to get the sense of how things will work together. A few comments on this diagram. You’ll notice that I’ve put all of the main application components inside a box I call Core. This is something I almost always do. These are the key components of the platform. You’ll also notice that I have the user interfaces talking to an API rather than directly to the Core. Again, this is a bit esoteric but it’s an important design principle at work.
I’ve also added the external components we’re going to use as a part of our platform. But it’s pretty dry and boring. Let’s make it look like something a bit more pro.
Here’s another drawing of the same thing but with the application component boundaries more clearly defined:
And so it goes. You can continue to refine as you go and get much more sophisticated, but if you’re just looking to communicate the concepts of the system and understand their interactions, this kind of diagram goes a long ways toward making the ideas clear for others.
Wrapping Up The Series
As with everything we’ve gone through in this series, documenting system components is a discipline that you need to have as a product owner of a technology product. And, as with everything else we’ve discussed, you can spend not enough time or too much time documenting. You’ll need to find the balance that works for you and your team over time.
As promised, here are links to artifacts and tools that we’ve discussed in this series. I hope this series has been beneficial for you! If you have any questions, please don’t hesitate to ask.
PlantUML Sequence Diagram Tool (you can also use this for data models)