Technical Design Document every software engineer should know about
Creating a well-structured technical design document, even for simple features, helps ensure clarity, facilitates focused team discussions, and serves as a record of technical decisions and thoughts
When planning a feature or application, a well-structured technical design document is essential. It ensures clarity, facilitates team collaboration, and helps anticipate potential challenges.
When I start working on any feature, I have a habit of creating a technical document, even for simple features. This practice helps me think early about the aspects I need to work on. I enjoy creating these documents because they provide a common ground for discussions with my team. The best part is that it keeps conversations focused and prevents them from going off-topic.
These documents are incredibly helpful for me and my team as they contain all the technical details and explain why particular technical decisions or technologies were chosen at the time. They serve as a record of everything our team considered during the feature development process.
Although this type of document is heavily influenced by backend development, you can tailor it based on your team’s context. Here’s what a robust design document should include:
Data Model
The data model is the backbone of your system's design. It should include:
Database tables: Define the schema, attributes, and relationships.
Updates and changes: Detail column additions, removals, or transformations in existing tables.
Version tracking: Maintain an updated record of changes to ensure alignment among team members.
Example for a Login API
Table Name:
usersAttributes:
id: UUIDemail: string (email format)password: hashed stringverified: boolean
API Design
API design must be clear and exhaustive, allowing teams to work independently and ensuring alignment. Here’s what to include:
Route: Define the endpoint path.
Method: Specify HTTP methods (e.g. GET, PUT, POST, PATCH).
Request: JSON structure expected in requests.
Response: JSON structure for successful responses.
Error Codes: List potential HTTP status codes and their meanings.
Use tools like Swagger to document APIs. API documentation enables frontend and backend teams to work in parallel, reducing dependencies and fostering early feedback.
Example:
Route:
/loginMethod:
POSTRequest
{ "email": "user@gmail.com", "password": "password" }Response
{"id": "7327fe0d-4904-48f2-8120-6dd69011b219","email": "user@gmail.com","verified": true,"access_token": "access_token"}Error Codes
200: Success401: Unauthorised
Swagger Document Example
Business Logic
Business logic should outline
Algorithms and workflows: Detail processing steps.
Special cases: Specify edge cases and how they are handled.
Alternatives: Provide pros and cons of various approaches to foster discussion.
Example, For a hypothetical login API, allow only users above 18 years to log in. Validate the user's date of birth against the current date.
Performance and Scalability
Design documents should address
Performance: Define how the system ensures low latency and efficient resource utilisation.
Scalability: Detail how the system will handle varying loads (e.g., auto-scaling mechanisms like AWS Lambda or Kubernetes).
Example, For a login API expecting high traffic during peak months, consider serverless options like AWS API Gateway and Lambda, which scale automatically based on demand.
Security Considerations
Security is paramount in API design. Cover aspects like
Authentication and Authorisation: Use JWT, API keys, or Basic Auth as needed.
Rate Limiting: Implement rate limits to prevent abuse (e.g., DDOS attacks).
Encryption: Ensure sensitive data, like passwords, is encrypted both at rest and in transit.
Example, For the login API, rate-limiting prevents repeated login attempts and reduces the risk of brute-force attacks.
Error Handling and Logging
Proper error handling and logging help in debugging and analytics.
Error scenarios: Define how to handle failures (e.g., third-party API outages).
Logs: Identify what needs to be logged (e.g., failed login attempts, successful logins).
Example, Log activities like:
Failed login attempts.
Repeated login failures exceeding a threshold.
Successful logins for analytics.
Risks and Mitigations
Anticipate potential risks and define mitigation strategies. For example Third-party API outages can be potential risk for your application which can be mitigated by implementing fallback mechanisms or retries.
You can use this template as an example for your work and modify it as needed. This document may not cover every case, as there could be additional aspects to consider and discuss before starting the work. Therefore, you should tailor it to suit your specific requirements.
A design document can vary in length depending on the nature of the feature being developed. Its scope may also depend on the company and the individual developer. In some organizations, good practices involve maintaining every tiny detail in technical documents.
However, it is always better to create a design document before starting your work. This practice clarifies what needs to be done early in the process and helps address unknowns before execution, making the approach more efficient. Such documents encourage critical thinking ahead of time, which is invaluable for your growth and progress in your career.
Consistently maintaining these types of documents fosters better habits over time, promotes team harmony, and facilitates more effective brainstorming within the team.