How do you document system assumptions and constraints?

1 What are system assumptions and constraints?

System assumptions and constraints are statements that define the scope and boundaries of your system design. Assumptions are things that you believe to be true or expect to happen, but are not verified or proven. Constraints are things that limit or restrict your system design, such as budget, time, performance, or security. For example, you might assume that your system will have a certain amount of users, traffic, or data, and you might constrain your system to use a specific technology, platform, or protocol.

2 Why document system assumptions and constraints?

Documenting system assumptions and constraints can help you and your stakeholders to communicate and align on the goals, expectations, and trade-offs of your system design, validate and test the design against the assumptions and constraints, evaluate different design alternatives, and track and update the design as the assumptions and constraints change. This will enable you to identify any gaps, risks, or issues, justify decisions and recommendations, and avoid scope creep or feature creep.

3 How to document system assumptions and constraints?

When it comes to documenting system assumptions and constraints, there is no one-size-fits-all approach. However, there are some general guidelines you should follow, such as using a consistent format and structure for your documentation and clear and concise language. Additionally, you should categorize and prioritize your assumptions and constraints, provide evidence and rationale for them, and review and revise them regularly. Make sure to document any changes or updates that occur.

4 How to document system assumptions and constraints with examples?

To illustrate how to document system assumptions and constraints, let's look at some examples from different system design scenarios. Note that these are not exhaustive or definitive examples, but rather illustrative ones.

5 # Example 1: Designing a URL shortening service

A URL shortening service is a system that takes a long URL and generates a short one that redirects to the original URL. Some possible assumptions and constraints for this system are:

| Assumption | Evidence/Rationale |

|------------|--------------------|

| The system will handle millions of URLs and requests per day. | Based on the market size and demand for URL shortening services. |

| The system will provide high availability and low latency. | Based on the user expectation and experience for URL shortening services. |

| The system will use a hash-based algorithm to generate short URLs. | Based on the simplicity and efficiency of hash-based algorithms. |

| Constraint | Evidence/Rationale |

|------------|--------------------|

| The system will use a fixed-length of 6 characters for short URLs. | Based on the trade-off between the number of possible short URLs and the length of the short URLs. |

| The system will use a relational database to store the mapping between long and short URLs. | Based on the need for consistency and durability of the data. |

| The system will use a load balancer and a cache to distribute and optimize the requests. | Based on the need for scalability and performance of the system. |

6 # Example 2: Designing a social media platform

A social media platform is a system that allows users to create, share, and interact with content, such as posts, comments, likes, and messages. Some possible assumptions and constraints for this system are:

| Assumption | Evidence/Rationale |

|------------|--------------------|

| The system will have billions of users and content items. | Based on the popularity and growth of social media platforms. |

| The system will support different types of content, such as text, image, video, and audio. | Based on the diversity and richness of social media content. |

| The system will use a graph-based model to represent the relationships between users and content. | Based on the natural and intuitive way of modeling social media networks. |

| Constraint | Evidence/Rationale |

|------------|--------------------|

| The system will prioritize read performance over write performance. | Based on the observation that read requests are more frequent and time-sensitive than write requests. |

| The system will use a combination of relational and non-relational databases to store different types of data. | Based on the trade-off between the consistency, availability, and scalability of different data models. |

| The system will use a microservices architecture to modularize and decouple different functionalities. | Based on the need for flexibility, maintainability, and extensibility of the system. |

7 How to document system assumptions and constraints with best practices?

To improve the quality and effectiveness of your system assumptions and constraints documentation, it is recommended to involve and consult stakeholders, such as users, customers, developers, or managers. Researching and benchmarking similar or existing systems can provide valuable insight into design choices, challenges, and solutions. Additionally, validating and verifying assumptions and constraints, as well as testing the system design against them using methods such as prototyping, simulation, or experimentation can be helpful. Furthermore, it is important to document and communicate assumptions and constraints clearly and transparently, and update them as the system design evolves.

8 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?