Software architecture for developers PDF download

The software architecture section is your “big picture” view and allows you to present the structure of the software. Traditional software architecture documents typically refer to this as a “conceptual view” or “logical view”, and there is often confusion about whether such views should refer to implementation details such as technology choices.

Intent

The purpose of this section is to summarise the software architecture of your software system so that the following questions can be answered:

• What does the “big picture” look like?
• Is there are clear structure?
• Is it clear how the system works from the “30, 000 foot view”?
• Does it show the major containers and technology choices?
• Does it show the major components and their interactions?
• What are the key internal interfaces? (e.g. a web service between your web and business tiers)

Structure

I use the container and component diagrams as the main focus for this section, accompanied by a short narrative explaining what the diagram is showing plus a summary of each container/component.

Sometimes UML sequence or collaboration diagrams showing component interactions can be a useful way to illustrate how the software satisfies the major use cases/user stories/etc. Only do this if it adds value though and resist the temptation to describe how every use case/user story works!

Code

Although other sections of the software guidebook describe the overall architecture of the
software, often you’ll want to present lower level details to explain how things work. This is
what the code section is for. Some software architecture documentation templates call this
the “implementation view” or the “development view”.

The purpose of the code section is to describe the implementation details for parts of the software system that are important, complex, significant, etc. For example, I’ve written about the following for software projects that I’ve been involved in:

• Generating/rendering HTML: a short description of an in-house framework that was created for generating HTML, including the major classes and concepts.
• Data binding: our approach to updating business objects as the result of HTTP POST requests.
• Multi-page data collection: a short description of an in-house framework we used for building forms that spanned multiple web pages.
• Web MVC: an example usage of the web MVC framework that was being used.
• Security: our approach to using Windows Identity Foundation (WIF) for authentication and authorisation.
• Domain model: an overview of the important parts of the domain model.
• Component framework: a short description of the framework that we built to allow components to be reconfigured at runtime.
• Configuration: a short description of the standard component configuration mechanism in use across the codebase.
• Architectural layering: an overview of the layering strategy and the patterns in use to implement it.
• Exceptions and logging: a summary of our approach to exception handling and logging across the various architectural layers.
• Patterns and principles: an explanation of how patterns and principles are implemented.

Keep it simple, with a short section for each element that you want to describe and include diagrams if they help the reader. For example, a high-level UML class and/or sequence diagram can be useful to help explain how a bespoke in-house framework works. Resist the temptation to include all of the detail though, and don’t feel that your diagrams need to show everything. I prefer to spend a few minutes sketching out a high-level UML class diagram that shows selected (important) attributes and methods rather than using the complex diagrams that can be generated automatically from your codebase with UML tools or IDE plugins. Keeping any diagrams at a high-level of detail means that they’re less volatile and remain up to date for longer because they can tolerate small changes to the code and yet remain valid.