Skip to content

Architecture and Technical Design Document Template

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>