Marqo Design Doc Template

(original source)

Author:

Date:

Stakeholders (sign-off required):

Status: Approved/Not-Approved w/ date

Instructions For Design Doc Authors

Fill every section in the template. Of course, you may determine that some sections may not be appropriate for your design, but if so, simply put the words “N/A” under them - do NOT delete the sections - they will serve as reminders to reviewers to double-check your assumptions on whether or not they are relevant.

Executive Summary

Provide a brief introduction to the document. Clarify its purpose and intended audience. Mention any prerequisites or background knowledge that would help the reader. Specify if the document is geared toward a technical or non-technical audience.

Problem Statement

Clearly define the problem that requires a solution. Provide relevant context about the problem, and reference any additional documents or resources where readers can learn more. Avoid abbreviations and assume the reader has no prior knowledge of the issue.

Glossary

Define any terms or abbreviations used in the document. Again, do not assume prior knowledge.

Tenets

Outline the core principles or beliefs that will guide decision-making during the design process. These principles help ensure alignment among the team. Tenets should be ranked in order of priority.

Examples:

• Customer Obsession: We prioritise the needs and experience of our end users in every decision we make. This means delivering a solution that not only meets functional requirements but also exceeds expectations in terms of usability, performance, and reliability. Any design choices that could negatively impact the user experience must be critically evaluated and justified.
• Reliability: The system should be highly reliable as this ties into the Customer Obsession tenet.
• Simplicity: We value simplicity in design as simple designs are easier to think about, having less moving parts. However, we rank it below Reliability because we value a more complex but reliable solution over a naively simple solution.

Functional Requirements

List all the functional requirements. Give each requirement an id that can be referred to later in this doc. Focus on the end user’s perspective: what do they expect from this solution? List all potential requirements and have them validated by stakeholders.

Example:

• FR-1: The user must be able to search with images
• FR-2: Search results should be paginated

Non-Functional Requirements

List all the non-functional requirements. Again, as in the Function Requirements section, give each requirement an id that can be referred to later in this doc.

Example:

• NFR-1: The system must have 5 9’s of availability
• NFR-2: p99 Latency should be 50ms

Out Of Scope

Clearly explain what is out of scope - explain why these items are out of scope.

Success Criteria

Consider the solution in production: how will its success be measured? What data will be used to evaluate it? Typically you should be able to define these using the Functional and Non-Functional requirements above.

API Design

Detail all the APIs (with examples) through which users or services will interact with this product or service. Include payloads, HTTP methods, versions, and discuss potential future evolution.

Starting with example API and python client interaction is a good idea as it sets the scene - working backwards towards the design from your customer’s/user’s perspective.

Architecture

Describe the architecture of the proposed solution. List the system components, focusing on the logical elements. Aim for a balance between detailed explanations and key diagrams or lists. Remember: a good diagram is worth a thousand words.

Typically for a reasonably complex problem there will likely be more than one way to solve it, as the author you should be opinionated about which of these solutions you are recommending here. There is opportunity in a subsequent section below to lay out the alternatives you considered.

Data Storage / Modeling

Define the data model and storage solution. Assess how much data the system will handle and project future growth. Ensure the solution will meet business needs for the next 3-5 years. Consider data pipelines, data ingestion, preprocessing, and the storage layer.

Low Level Design

Provide a detailed design of each individual component. Include components, data flow, control flow diagrams, and any other relevant details. You can optionally consider splitting this out into a separate document to avoid getting into the weeds here. If you do so, leave a placeholder link instead in this section.

Dependencies

Explicitly state the systems your solution will interact with, both internal and external. Dependencies can introduce risks, so thorough analysis and risk mitigation are essential. Outline any assumptions about these dependencies, such as, “We assume Amazon ECS can handle 1000 concurrent tasks per cell/AWS account.”

Engineering Excellence

Consistency and Integrity

• Dive into any areas which raise consistency/race condition concerns
• Even if race conditions/consistency issues aren't present with your design, if you flesh these scenarios out, it shows that we've done sufficient investigation
• Add an example of race conditions like this:

• User A does action X

• User B does action Y

• User A's request sets record Q to P

• etc.

Reliability & Resilience

• How are we guaranteeing resilience in the service?
• Failure modes, and how they are handled?

Scalability

Estimate the number of users, transactions, and data volume. At what point do we expect to see bottlenecks with the proposed solution? What constraints do our chosen dependencies put on the system?

Observability

A lot of this section should be covered by an ORR, but it’s worth describing some high level metrics and dashboards you plan to provide as part of this project.

Security

• Specify the required level of security based on the system’s data and interactions?
• What are we doing to enforce the principle of least privilege?

Testing

Outline the approach to unit tests, integration tests, stress tests, and the tools that will be used. Remember to follow our Testing Approaches EDR.

Be specific with a list of use-cases that you need to add (or modify existing) tests for. This list should be useful for both implementors and PR reviewers alike.

Key Risks

Identify the key risks and concerns that could impact the project, such as external dependencies or resource constraints.

Future Improvements (Optional)

Discuss potential features or enhancements that could be introduced in future releases. Outline the expected timeline for these improvements.

Cost Analysis

Estimate the infrastructure costs associated with the solution. This section may be optional for smaller projects, but it’s generally useful to calculate the impact to ensure the right solution is chosen. Plan for future growth.

If your project involves a large scale performance test, please include the cost estimate and timeline for that test.

Release / Roll-out

High level estimate on how long it will take to roll out the project.

Ideally look for opportunities to roll it out in phases instead of a big-bang.

How are you ensuring backward compatibility?

Remember to also detail a rollback strategy in the event of unforeseen failure.

Impact on other components

List out how the changes made will impact other components. Think about dependent components that could be affected, and what changes they need to make to accommodate this.

Also, think about how other components need to be updated to properly support a new feature. For example: UI changes, and changes required for observability and safety tools.

Alternative Solutions Considered

Discuss the different design alternatives considered, including various infrastructure platforms, databases, service frameworks, and logical approaches. Again, diagrams are helpful even for these discarded solutions.

Explain why the chosen solution is recommended. Include a table comparing alternatives based on criteria like cost, scalability, ease of use, latency, maintainability…

FAQs

Include common questions and answers to streamline the review process. If the design is new, anticipate possible questions and provide answers.

References

Links to prior art, competitor analysis, any other relevant documents.

Appendix

Include detailed technical analyses, data, or in-depth investigations that may be of interest but aren’t essential for everyone to review.

Design Review Follow-ups

Fill in any action items and next steps derived from the review.