High-level design document and how it can help us to structure your design artifacts
Previous: https://medium.com/@svosh2/stakeholder-driven-presentation-and-high-level-diagrams-ad20cdc6ecd3
A high-level design document (HLDD) is a document that provides an overview of the architecture and design principles of a software system at a conceptual or abstract level. It focuses on the system’s structure, components, and major interactions, without delving into implementation details. The HLDD serves as a reference for stakeholders, including developers, architects, project managers, and business stakeholders, to understand the overall design approach and make informed decisions. it combines all the high-level artifacts from the previous chapters. Here’s an outline of possible contents and sections found in a high-level design document:
Introduction:
Provides an overview of the purpose, scope, and objectives of the document, including a brief description of the system being designed and its intended functionality.
Example: This High-Level Design Document provides an in-depth overview of the architecture and design principles for the Goods Store System. The system aims to streamline the operations of a retail store that sells various goods, including electronics, clothing, and household items, to customers. The scope of this document covers the high-level design of the system, including its major components, data flow, user interfaces, and external integrations.
Functional requirements and non-functional requirements sections:
We mentioned these requirements in the previous chapters. Now in our HLDD we want just list them to be sure, that all the functionality and target properties will be covered.
Architectural Overview:
Describes the high-level architecture and design principles of the system. Identifies the major components, subsystems, or layers within the system. Outlines the relationships, dependencies, and interactions between the components.
Example: The Goods Store System follows a layered architectural pattern, consisting of multiple interconnected components that work together to fulfill the system’s objectives. The architecture ensures separation of concerns and modularity, facilitating scalability, maintainability, and extensibility. The following are the key architectural components:
Presentation Layer:
The presentation layer is responsible for handling user interactions and rendering the user interfaces. It includes front-end components such as web pages, mobile apps, or any other user interface elements that allow customers to interact with the system. The presentation layer communicates with the back-end components to retrieve and display relevant data.
Business Logic Layer:
The business logic layer contains the core functional logic and rules of the Goods Store System. It processes user requests, applies business rules, and orchestrates interactions between various components. This layer encapsulates domain-specific operations, including product catalog management, order processing, and customer management.
Integration Layer:
The integration layer enables communication between the Goods Store System and external systems or services. It handles integration with third-party payment gateways, inventory management systems, or any other external systems involved in the retail store’s operations. The integration layer ensures seamless data exchange and interoperability between the Goods Store System and external entities.
Data Layer:
The data layer consists of the database and associated components responsible for data storage and retrieval. It stores product information, customer profiles, order details, and inventory records. The data layer interacts with the business logic layer to provide data persistence and retrieval functionality.
This section is a good place to leave our Context C4 diagram. You also can bring a bit more detail to it and show it in the layered structure (for the example above). Here you can ignore the specific technologies, protocols, and flows.
System Components:
Provides a description of the major components or modules of the system. Describes the purpose, responsibilities, and functionality of each component. Highlights the interfaces, inputs, outputs, or interactions with other components.
Example: The Goods Store System is composed of several interconnected components, each serving specific functions and contributing to the overall system’s capabilities. These components work together to provide a seamless and efficient retail store management solution. The following are the key components of the Goods Store System:
User Interface Component:
The User Interface Component encompasses the front-end elements of the system, enabling customers to interact with the store’s products, browse catalogs, add items to the cart, and complete the checkout process. It provides an intuitive and responsive web-based interface that allows customers to search for products, filter based on categories or specifications, view product details, and manage their shopping cart. The User Interface Component also includes an administrative interface that enables store managers to perform various tasks, such as managing inventory, processing orders, and generating reports.
Order Processing Component:
The Order Processing Component handles the end-to-end processing of customer orders, ensuring a smooth and timely order fulfillment process. It facilitates the secure capture and validation of customer information, including shipping addresses, payment details, and any special instructions. The Order Processing Component coordinates with external payment gateways to securely process payments, confirms order placement, and generates order confirmation notifications.
Inventory Management Component:
The Inventory Management Component is responsible for managing the store’s inventory, including tracking product availability, and stock levels, and ensuring accurate inventory data. It enables store managers to add new products, update stock quantities, and handle inventory-related operations such as restocking, backorders, or product discontinuation. The Inventory Management Component also supports automated notifications to store managers when inventory thresholds are reached or when specific products require attention.
Customer Management Component:
The Customer Management Component facilitates the management of customer information, including registration, profile updates, and order history. It provides customer account creation and authentication mechanisms, allowing customers to securely access their account details and track their orders. The Customer Management Component supports features such as personalized recommendations, wish lists, and loyalty programs to enhance customer engagement and retention.
Reporting and Analytics Component:
The Reporting and Analytics Component enables store managers to generate reports and gain insights into sales performance, customer behavior, and product popularity. It provides predefined reports and customizable analytics dashboards, allowing store managers to monitor key performance indicators, track revenue, identify trends, and make informed business decisions. The Reporting and Analytics Component helps store managers optimize product offerings, inventory management, and marketing strategies based on data-driven insights.
This section is a perfect fit for our Container C4 diagram. This diagram in tandem with a description from the example above will give a pretty good understanding of the structure of the system.
Data Flow and Processing:
Illustrates the flow of data or information through the system. Describes how data is received, processed, transformed, and delivered within the system. Identifies the key data sources, data transformations, and data destinations.
Example: The Goods Store System involves the flow of data and information across various components to support the retail store’s operations, customer interactions, and inventory management. The following describes the key data flows and processing within the system:
Customer Interaction:
When customers interact with the User Interface Component, they initiate data flows by browsing products, adding items to the cart, and proceeding to the checkout process. The User Interface Component collects customer input, such as product selections, quantities, and payment information, and sends it to the Order Processing Component for further processing.
Order Processing:
The Order Processing Component receives customer order data from the User Interface Component. It validates the data, including verifying product availability and checking for any potential errors or inconsistencies. The Order Processing Component coordinates with external payment gateways to securely process customer payments. Once the order is validated and payment is confirmed, the Order Processing Component generates an order confirmation and notifies the Customer Management Component and the Inventory Management Component about the new order.
Inventory Management:
The Inventory Management Component receives the order information from the Order Processing Component. It updates the inventory by reducing the available stock quantities for the ordered products. The Inventory Management Component ensures real-time synchronization between the system and the actual store inventory, reflecting accurate stock levels to prevent overselling or inventory discrepancies. In case of low stock levels, the Inventory Management Component may trigger notifications to store managers for restocking or taking necessary actions.
Customer Management:
The Customer Management Component stores and manages customer data, including customer profiles, order history, and preferences. It receives customer information from the User Interface Component during registration or order placement. The Customer Management Component updates the customer’s order history and account details with each new order. It provides store managers access to customer information and order history for personalized customer support and targeted marketing initiatives.
Reporting and Analytics:
The Reporting and Analytics Component collects relevant data from various components, including order data, customer information, and product performance. It processes and analyzes the collected data to generate reports, statistics, and visualizations that offer insights into sales trends, customer behavior, and product popularity. Store managers can access these reports and analytics through the administrative interface to make informed decisions regarding inventory management, marketing strategies, and future product offerings.
Use case, Sequence, and Flow diagrams can be a great addition to the explanation above. This section will bring details about the system’s behavior.
User Interface (if needed):
Provides an overview of the user interface design approach. Describes the key screens, user interactions, and navigation flows. May include wireframes, mockups, or screenshots to visualize the user interface.
Example: The Goods Store System incorporates a user-friendly and intuitive user interface that enables customers to browse products, add items to their cart, and complete the checkout process. The user interface also provides an administrative interface for store managers to manage inventory, track sales, and generate reports. The following describes the key features and functionalities of the user interface:
Customer Interface:
Product Browsing: The customer interface allows users to search for products, browse product categories, and filter products based on specifications, price range, or other attributes. It provides a visually appealing display of product listings, including product images, descriptions, and pricing information.
Product Details: Customers can view detailed information about a specific product, including its specifications, available sizes, colors, and customer reviews. The interface provides an interactive display with zoom capabilities for product images. Shopping Cart Management: Users can add products to their shopping cart, view the cart contents, modify quantities, and remove items as needed. The interface provides a summary of the cart, including the total cost, applicable discounts, and shipping options.
Checkout Process: The interface guides customers through a seamless checkout process, collecting shipping information, payment details, and any special instructions. It verifies the order details, calculates applicable taxes and shipping costs, and provides a summary before confirming the order placement.
Administrative Interface:
Inventory Management: The administrative interface enables store managers to manage the store’s inventory. They can add new products, update existing product information, set stock quantities, and track product availability. The interface provides a user-friendly form-based interface for efficient inventory management.
Order Processing: Store managers can access order details, view the status of customer orders, and process order fulfillment. They can update order statuses, track shipment information, and generate invoices or packing slips as required. The interface allows store managers to efficiently handle customer inquiries, refunds, or order cancellations.
Sales Reporting: The administrative interface provides access to sales reports and analytics. Store managers can generate reports to monitor sales performance, track revenue, and identify trends. The interface may include customizable dashboards and visualizations to provide a comprehensive view of sales data, customer behavior, and product performance.
Customer Management: The interface allows store managers to manage customer profiles, view customer order history, and track customer interactions. Store managers can update customer information, handle customer inquiries, and provide personalized customer support.
For sure we only need this section when some UI is present. Here we use our User Interface (UI) Walkthroughs. This section shows what our system looks like for its users.
External Interfaces (if needed):
Describes the integration points and interfaces with external systems, services, or APIs. Specifies the communication protocols, data formats, or security considerations for interacting with external components.
Example: External Interfaces:
The Goods Store System integrates with external systems and services to enhance its functionality and provide a seamless experience for customers and store managers. The following describes the key external interfaces, the protocols used, and the data formats exchanged within the system:
Payment Gateway Integration:
Protocol: The Goods Store System communicates with the payment gateway using secure communication protocols such as HTTPS.
Data Formats: The payment gateway integration typically involves exchanging data in industry-standard formats such as JSON (JavaScript Object Notation) or XML (eXtensible Markup Language) for requests and responses. The specific data format may depend on the requirements and specifications of the payment gateway provider.
This description may be added to a table with an API endpoint (protocol, name, description, path, examples of request/response). OpenAPI file is also an option.
Deployment and Environment:
Provides an overview of the deployment architecture and deployment considerations. Specifies the hardware, software, or infrastructure requirements for running the system. Discusses any specific dependencies or configurations needed for different environments.
Example: Deployment and Environment:
The Goods Store System is deployed in a cloud-based environment, leveraging the benefits of scalability, availability, and flexibility. The deployment infrastructure and environment are designed to ensure high performance and reliability. The following describes the key aspects of the deployment and environment for the Goods Store System:
Cloud Infrastructure:
The system is hosted on a cloud platform, such as Amazon Web Services (AWS), Microsoft Azure, or Google Cloud Platform (GCP).
Virtual Servers: The Goods Store System utilizes virtual servers provided by the cloud platform. These servers are scalable, allowing for dynamic allocation of resources based on demand.
Load Balancers: Load balancers are employed to distribute incoming customer requests across multiple instances of the system, ensuring efficient utilization of resources and balancing the workload.
Autoscaling: Autoscaling capabilities are utilized to automatically adjust the number of system instances based on traffic patterns and resource utilization. This allows for optimal performance during peak periods and cost savings during low-demand periods.
Backup and Disaster Recovery:
Regular backups of the system’s data are performed to ensure data integrity and resilience against potential data loss or corruption.
Backup Storage: The system’s data backups are stored in secure and resilient storage systems, both within the cloud platform and potentially in off-site locations.
Disaster Recovery Plan: The system incorporates a comprehensive disaster recovery plan that outlines procedures for system recovery and data restoration in the event of a catastrophic event or failure.
Failover Mechanisms: Redundancy and failover mechanisms are in place to minimize downtime and ensure seamless continuity of operations in the event of a failure in one part of the system.
Development and Testing Environments:
Separate development and testing environments are established to facilitate software development, testing, and quality assurance processes.
Development Environment: The development environment provides a sandboxed environment where developers can work on new features, perform code changes, and conduct unit testing.
Testing Environment: The testing environment mimics the production environment, allowing for comprehensive testing of the system’s functionalities, performance, and integration with external systems.
Here we would add Deployment diagrams that will describe our ideas in this area in a more informative manner.
Note: Depending on which system properties (non-functional requirements) were defined — there can be additional sections to describe part of the design that cover these properties:
Performance Considerations:
Outlines the high-level performance requirements and considerations for the system. Discusses factors such as response times, throughput, scalability, or resource utilization. This may include performance goals or constraints that influence design decisions.
Security Considerations:
Addresses high-level security requirements and considerations for the system. Discusses authentication, authorization, data protection, or other security mechanisms. Identifies potential vulnerabilities or risks and outlines security best practices.
Error Handling and Exception Management:
Describes the approach to handling errors, exceptions, or unexpected situations in the system. Specifies how errors are detected, reported, logged, and handled within the system.
Risks and Mitigation Strategies:
Highlights potential risks, challenges, or uncertainties related to the system design. Discusses strategies or mitigation plans to address identified risks.
Note: The last few sections are usually about some additional information. Here are a few examples of what can be placed there:
Assumptions and Constraints:
Documents any assumptions or constraints that impact the system design. Identifies any limitations, dependencies, or architectural decisions based on specific constraints or requirements.
Glossary and References:
Includes a glossary of terms used throughout the document. Lists any external references, standards, or frameworks that were utilized in the design process.
Note: HLDD preparation is an iterative process. During it, you will always return back to your stakeholders, retrieve new requirements, and bring new details. A design document for sure will have a series of review meetings. To manage all the history of changes sometimes a “revisions” section can be added into a document. Modern documentation tools such as Confluence give us a changes history for our documentation out of the box.
Now let’s go to the last article of this series and see, how the development process for our design can be managed and supported.
