Technical Design Document - Microservice

A Technical Design Document (TDD) is written by the development team and describes the minute detail of the entire design of the system that the team is going to build. It's is a design blueprint for an application or feature.

It should include both functional and technical design. The functional design specifies how a program will behave to outside agents and the technical design describes how that functionality is to be implemented in code.

The primary function of a TDD is to,

• 🗣️ Communicate the technical details of the work to be done to members of the team and clients.
• 💡 Gain clear understanding of the system to built. Which will help in planing the development.

The process of writing the TDD forces to organize thoughts and consider every aspect of the design, ensuring that we haven’t left anything out.

How do i know? 📜

I recently got hands on a monolithic system where the stakeholders gave us a problem that there is too much dependency. They had almost 5-6 team working on a single code base and it was almost impossible for the teams to sync with a single release cycle. Hence too much of unfinished code started moving to production, causing many issues.

Thus we were tasked to create a microservice for one of the module. Luckily, thanks to by team lead, I got the opportunity to do the work. Hence I got to create a TDD. Got involved in many discussions and refined the TDD. It was an eye opener, despite having some experience previously in similar work.

Writing a TDD 📖

Writing TDD is exciting because its about building a new system / feature. But TDD is not something that can be written overnight. It is a long progress often with many review cycles. It must go through BA (Business Analyst), project lead, project manager and stakeholders. Hence should be written clear and crisp. It must be well detailed explaining the following:

• Product requirements - Here the feature overview and justification is written. This section must answer two important questions. What is the problem identified? and what are the goals?
• Technical requirements - The product requirements are translated into technical requirements — what the system needs to accomplish? More like goals.
• Technical design - This contains a technical design of the solution to the requirements outlined in the previous steps. This should explain what will be the system architecture? What will be the system inputs? and what should be the expected outputs? Lot of flow diagrams will help to understand the design quicker.
• Implementation - This explains how we are planing to execute the design. Generally split into phases, where each phase delivers executable and working part of the output. Final phase will deliver the complete product.
• Testing - This should explain how testing is planned. Manual or automation? Should we include load testing? Why so?
• Release process - This should outline the plan with respect to releases. At which dates each phase and the final product will be available to the customers.

Bounded context - Bounded Context is a central pattern in Domain-Driven Design. The general rule is that a service should do "one thing". For example, if we set sales as the boundary context then this service must only be responsible for sales data and features. Other features like support should not be accessed directly or updated in this service. However, only when absolutely necessary, sales service can communicate with support service for any data exchange. More about bounded context here (https://www.martinfowler.com/bliki/BoundedContext.html)[https://www.martinfowler.com/bliki/BoundedContext.html]

TDD Template

First page

Name TDD
Status: Draft / In Progress / In Review / Approved

Overview

Problem Identified

Describe about the problem in detail. Explain the impacts and issues that the problem is causing.

Goals identified

List the goals to achieve for solving the problem. Describe about each goal in short sentences.

Supporting documents

List of supporting documents that can be additional reading.

Technical overview

Existing system architecture

Describe about existing system architecture. This could include an architecture diagram and description.

Execution plan

Describe about proposed system architecture. This could include an architecture diagram and description.

Data Model

Describe how the data is stored. This could include a description of the database schema.

Interface/API Definitions

Describe how the various components talk to each other. For example, if there are REST endpoints, describe the endpoint URL and the format of the data and parameters used.

CI/CD

Describe on how to automate continuous code integration and continuous deployment. Explain the strategy and tools to be used.

Fault tolerence

Describe the fault tolerance strategy. How will the system react to various known / unknown issues.

Open Questions and Assumptions

Add any unanswered questions or assumptions here.

Abandoned Ideas

Describe any ideas that were discussed but not considered for the design or solution.

Additional observations / Tips 💁‍♂️

• Draw as much as you can. 1 picture can explain 1000 words. No matter how hard you try, it's difficult to explain to multiple readers. Sometimes if it's too long, it can get frustrating to read. Hence create flow diagrams, architecture diagrams, bullet points, etc... You can use draw.io or Whimsical
• 60% of TDD I built was of diagrams. This actually helped in understanding. One of the reviewers actually confirmed that there were lesser doubts especially because of the diagrams. It helped in understanding the design.
• Often we can easily explain things in single line just like in emails. But that never works out in TDD because the readers here are both experienced engineers and also business stakeholders. We will receive many questions. Thus we need to be clear on every claim or fact that we add in the document. For example, if we are to say that the API performance will improve. Though it might be obvious, we are supposed to tell how? and by how much it improves? Perhaps even do a POC to get the metrics. But we must have the metrics else it's hard to prove the statements.
• Some popular questions - Why? Why should we do this? Why exactly like this? Why not use different method?
• Always remember to check for the best possible ways. If there are multiple ways, do mention them and also confirm which to pick.
• Always plan in incremental release model. (i.e) Create the product in small working parts. Hence every part is testable and can be released to production in quick time.

Finally

Hope it was helpful. Let me know your experience of building exciting systems in the comments !! Have a good day !!