Software Architect Design Documentation Template

1. Software
Architect
Documentation
Guide Book
January 20
2015
By SalimBhonhariya(CloudArchitect)
Designed
Software
Guide Book

2. 1
1
Contents
Context..............................................................................................................................................3
What isthisall about?Designdetailswhichcontaindetailsnecessarytobuildthe systembutnot
needed to reason about failure. These details are not architectural...................................................3
Functional Overview...........................................................................................................................3
What does the system do?..............................................................................................................3
Functional requirements:................................................................................................................3
Context:.........................................................................................................................................3
Container:......................................................................................................................................3
Component:...................................................................................................................................3
Classes:..........................................................................................................................................3
Quality Attributes...............................................................................................................................4
Are there any significant non-functional requirements?....................................................................4
Constraints.........................................................................................................................................4
Are there any significant constraints? ..............................................................................................4
Principles ...........................................................................................................................................4
What design and development principles have been adopted? .........................................................4
Software Architecture.........................................................................................................................5
What does the big picture looklike and how is the system architecture?...........................................5
External Interfaces..............................................................................................................................6
What are the external systems interfaces?.......................................................................................6
Code..................................................................................................................................................6
Implementation details need to be explained?.................................................................................6
Structure ...................................................................................................................................6
Vision ........................................................................................................................................6
Technical Risks.........................................................................................................................6
Data...................................................................................................................................................7
What does the data model looklike andwhere it is being stored?.....................................................7
Infrastructure Architecture..................................................................................................................7
What does the target deploymentenvironment look like?................................................................7
Deployment.......................................................................................................................................7
What is the mapping between software andinfrastructure? .............................................................7

3. 2
2
Operation and Support .......................................................................................................................7
How will people operates and support the system............................................................................7
Decision Log.......................................................................................................................................7
What decisions are takenwhile designing this document? ................................................................7

4. 3
3
Context
What is this all about? Design details which contain details necessary to build
the system but not needed to reason about failure. These details are not
architectural.
Functional Overview
What does the system do?
Functional requirements: Requirements drive architecture. You need to know
vaguely what you’re building, irrespective of how you capture and record those
requirements (i.e. user stories, use cases, requirements specifications, acceptance
tests, etc.).
Explain how your software system works at various levels of abstraction? What
concepts and levels of abstraction would you use to do this?
Use UML to visualize the design of your software.
Create software architecture diagrams for your software system which represent
the codebase
Context: A high-level diagram that sets the scene; including key system
dependencies and actors.
Container: A container diagram shows the high-level technology choices, how
responsibilities are distributed across them and how the containers
communicate.
Component: For each container, a component diagram lets you see the key
logical components and their relationships.
Classes: This is an optional level of detail and I will draw a small number of high-
level UML class diagrams if I want to explain how a particular pattern or
component will be (or has been) implemented. The factors that prompt me to
draw class diagrams for parts of the software system include the complexity of

5. 4
4
the software plus the size and experience of the team. Any UML diagrams that I
do draw tend to be sketches rather than comprehensive models
Quality Attributes
Are there any significant non-functional requirements?
The non-functional requirements (e.g. performance, scalability, security, etc.) are
usually technical in nature and are hard to retrofit. They ideally need to be baked
into the initial design and ignoring these qualities will lead you to a software system
that is either over- or under-engineered.
Constraints
Are there any significant constraints?
Constraints: The real-world usually has constraints; ranging from approved
technology lists, prescribed integration standards, target deployment environment,
size of team, etc. Again, not considering these could cause you to deliver a
software system that doesn’t complement your environment, adding unnecessary
friction.
Principles
What design and development principles have been adopted?
Principles: These are the things that you want to adopt in an attempt to provide
consistency and clarity to the software. From a design perspective, this includes
things like your decomposition strategy (e.g. layers vs components vs micro-
services), separation of concerns, architectural patterns, etc. Explicitly outlining a
starting set of principles is essential so that the team building the software starts
out heading in the same direction.

6. 5
5
Software Architecture
What does the big picture look like and how is the system architecture?
Model of all possible failures in the system called risk and reason about those
risks. When the system fails you know that you have a reason to fail and how to fix
it.
You include the details in the model only if you have reason about failure about the
system to identify. You omit other design details.
Details design is architectural only if it can be traced back to avoiding failure risk.
That is how we know that the information detail is architectural.
The model helps you reason about and failure you are worried about. Detail you
have in model is architectural.
Cross-cutting concerns such as logging and exception handling.
Security; including authentication, authorization and confidentiality of sensitive
data.
Performance, scalability, availability and other quality attributes.
Audit and other regulatory requirements.
Real-world constraints of the environment.
Interoperability/integration with other software systems.
Operational, support and maintenance requirements.
Consistency of structure and approach to solving problems/implementing features
across the codebase.
Technology choices.

7. 6
6
External Interfaces
What are the external systems interfaces?
Code
Implementation details need to be explained?
Structure
1. What: Understand the significant structural elements and how they fit
together, based upon requirements and constraints.
2. How: Design and decomposition down to containers and components.
Vision
3. What: Create Technical strategy, Vision, Roadmap and communicate
a vision for the team to work with.
4. How: Context, container and component diagrams.
Technical Risks
5. What: Identify and mitigate the highest priority risks. To insure that the
architecture works.
6. How: Risk-storming and concrete experiments
7. Project Documentation

8. 7
7
Data
What does the data model look like and where it is being stored?
Infrastructure Architecture
What does the target deployment environment look like?
Deployment
What is the mapping between software and infrastructure?
Operationand Support
How will people operates and support the system.
DecisionLog
What decisions are taken while designing this document?