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?