Below are Architecture and Technical Design Document Templates I created. They are starting points. There are many other import key ideas/significances that can be added depending on business requirements, platforms, and technologies being used.
Introduction
This document contains both architectural and technical design documents. Depending on the teams, organizational structure, and audience, most of the time, these documents are separated for relevance, focus, clarity, and target audience.
The first part will focus on architecture and the second part on technical design. Technical best practices such as naming convention, coding standard, and similar can be put into a separate document because they apply to all projects.
Do not edit or delete the italic text of each section because it provides direction and context of that particular section.
Architecture
This part focuses on architecture covering business drivers, key significances, quality attributes, patterns, principles, best practices, project software life expectancy, business agility, type of users, volume, return of investment (ROI), and others that are relevant to the project purposes and objectives.
Some key questions to ask are:
- What exactly does the business want this software system to do?
- What do you need to do to achieve the business objectives?
- How do you go about to achieve that?
The audience for this part include executives, business analysts, project managers, architects, DevOps, and other key stakeholders.
If any section below does not apply, put NA. Not all sections need to be done at once. For example, the deployment section can be delayed later.
Business Value
Describe the business drivers, key significances, and other business values expect from this software.
<To do>
Business Fluctuation and Volume
Describe the business volume and fluctuation of using this software system. What are the forecasts for short term and long term?
<To do>
Business Agility and Adaptability
Describe the short term and long term the business has to adapt and the time to respond for changes. To what extent and frequency the system has to change?
<To do>
Software life expectancy
How long does the business plan to use this software system? How will it be sunset? Is there a new system to replace it?
<To do>
Approach to Architecture
Describe the approach to this architecture. What are other options that have explored and what are the key criteria taken in consideration to make this choice?
<To do>
Quality Attributes
Describe the key characteristics or quality attributes that this architecture achieves and why they are significant.
<To do>
Constraints
List and describe these constraints in the view of existence, significances, impact to the software system, usage, limitations, and validations.
<To do>
Architecture Artifacts
Provide conceptual, logical, and deployment diagrams such as block diagram, use case diagram, component diagram, data flow diagram, and deployment diagram with brief and concise description. Make sure architectural diagram is tidy, same level of contextual information, and no spaghetti diagram for clarity, single purpose, and easy to understand. A diagram should take no more than a minute to grasp and understand.
Conceptual and Use Case Diagram
Provide high level conceptual diagram and/or use case diagram with brief description.
<To do: Conceptual Diagram>
<To do: Describe the purpose of the diagram and its delivery>
Component and Data Flow Diagram
Provide component and data flow diagrams. For component, describe what each component does, what are the input/upstream, output/downstream, and its dependencies on other components or external systems and environments. At this level, it is not appropriate to provide detail message structures, attributes and their respective types and network protocols. Put these in the technical design section.
<To do>
Deployment Diagram
Provide deployment diagram and describe the layout. If it is deployed into Google Cloud Platform, show the pod and its number of containers, replicas and label how Google service can discover and route to it. Also, it is best to show the number of pods, nodes, and Kubernetes Masters for resilient purpose. Leave the manifest deployment detail in the technical design section.
<To do: Deployment Diagram>
Technical Design
This part is a technical design document to capture the technical approach, technical design, and technical design selection.
The audience for this part include architects, technical lead, software engineers, developers, and programmers.
Follow through the applicable part and fill in every section. If for any reason a particular section does not apply, put NA or Not Applicable and the reason why not applicable.
Approach to technical design
Describe the technical design approach.
<To do>
Other alternative technical design consideration
Provide other alternative technical design consideration that have looked into.
<To do>
Rationale of selected technical design with pros and cons
Provide the key significances of choosing this approach instead of the others. Briefly and concisely describe the important points of the pros and cons to help other understand the rationale.
<To do>
Technical design
Provide detail and complete technical design. May include any type of diagrams to support clarity, context, point of view, and understanding. Describe the goals and purposes this design will solve.
<To do>
Dependencies
List and describe all the dependencies this service has on other systems.
<To do>
Input, output, upstream and downstream
List and describe all the input, upstream, output and downstream of this service. Provide detail protocols being used, message formats, message structures, and property names and their respective data types.
<To do>
Properties and configuration setup
Define all properties and configuration setup and their locations. Also include deployment manifest file and environment variables.
<To do>
Project Structure
Provide the project structure using package diagram and their dependencies with brief description.
<To do>
Control flow
Provide sequence diagram and/or class diagram along with brief description of various contextual control flows.
<To do>
Dependent Libraries
List all libraries that this project depends on. If the list is available in other location, provide the path or URL to.
<To do>
Deployment
Describe in detail how and where this software will be deployed to. What are the required deployment files like manifest, Docker image, configuration file, and environment variables. Provide all the technical detail deployment in conjunction with the deployment section at the architecture level above.
<To do>