Design

System diagrams and drawings

It’s important to have a good foundation when building quality solutions, and drawings and diagrams showing the infrastructure, data flow, networks, and access control are crucial elements. Without this information, it is difficult to validate if the implementation matches the intended design.
Last modified October 27, 2026 Written by Christoffer Hafsahl and Andreas Skaret
Print entire section

When designing a solution, it’s essential to have clear and comprehensive drawings and diagrams that show the planned design. This is already done by many development teams without necessarily being a formal requirement, but it’s still worth mentioning here.

System diagrams should provide enough information to:

  • Validate that the implementation matches the design
  • Use them for threat modeling, pentesting, or similar activities
  • Be used by those managing the solution to get a good overview of components and data flow
  • Be used by the delivery team for onboarding new colleagues or handover to other teams

Although there is a lot that can be documented here, we focus on the most important aspects:

  • High-level system sketch with the main logical components
  • Detailed network diagram with resources, services, and networks
  • Data flow diagram showing how data flows between components in the solution
  • IAM diagram showing identities, accesses, and roles and where they are sourced from
  • Important dependencies – overview of other systems, services, resources, on-prem/cloud

Use of AI components

If the solution includes artificial intelligence or machine learning models, these should be explicitly documented in the system documentation:

  • In the data flow diagram: Show where training data and inference input come from, and how results continue through the system
  • In the network diagram: Document where the model runs (cloud API, edge device, on-prem server) and related network connectivity
  • In the dependencies list: Include model ownership, versioning, and where updates happen
  • In the IAM diagram: Show who can deploy, update, or monitor the model

Without this information, it is difficult to maintain a clear overview of risk, data flow, and compliance around AI components.

Examples

Below are examples of the points listed above. The diagrams you produce do not need to be identical; the most important thing is that they contain enough information to be used for their intended purpose and are understandable to the team.

To easily get started with designing diagrams and sketches, tools like Miro or Draw.io can be used. The latter is free and offers storage of drawings in the browser, locally on the machine as XML, and much more.

Keep in mind:

The diagrams do not need to be perfect or contain every conceivable detail. Assess the need and work on gradual improvements over time.

High-level System Diagram

This diagram should be a high-level introduction to the solution, showing all the major components and interactions between them.

High-level system sketch The frontend talks to the backend. The backend reads from two databases, On-prem SQL and Azure SQL, and exchanges data with the company data platform, which is a dependency outside the solution. The backend also feeds Power BI Reports, which additionally reads from the data platform. Frontend Backend Power BI Reports Company data platform (dependency) On-prem SQL Azure SQL
Example of a high-level system sketch. It shows only the largest components and how they relate to each other. Dependencies outside the solution are dashed, so it is easy to see what the team controls itself.

Network Diagram

The goal of the network diagram is to show the network topology, with all the various virtual networks, subnets and resources or servers and firewall openings between them. A good network diagram visualizes the data flow between points for everyone to see, not just developers.

Network diagram for a development environment An internal user reaches an Azure Firewall over HTTPS 443. The firewall passes traffic on to the Frontend-dev subnet (10.0.0.0/27), which holds an app service and a key vault, and to the Dev workspace reporting area with two reports. Both continue to an Azure WAF, which lets traffic into the Backend-dev subnet (10.0.0.32/27). That subnet holds two app services and an ingress factory, all of which use the same SQL database and key vault. The ingress factory pulls data from the datalake-somedata-prod01 data lake in the company data platform, which sits outside the environment. Internal user HTTPS 443 Azure Firewall Frontend-dev 10.0.0.0/27 frontend-dev-appsvc 10.0.0.2 frontend-dev-keyvault Dev workspace Report 1 Report 2 HTTPS 443 HTTPS 443 Azure WAF HTTPS 443 Backend-dev 10.0.0.32/27 backend-dev-appsvc01 10.0.0.36 backend-dev-appsvc02 10.0.0.37 ingress-factory-dev-01 10.0.0.43 backend-dev-sql01 10.0.0.40 backend-dev-keyvault 10.0.0.50 HTTPS 443 Company data platform (dependency) datalake-somedata-prod01 10.10.10.10
Example network diagram for a development environment. Every subnet is labelled with its address range, every resource has its own address, and the arrows show the direction of traffic and which port is open. The reporting workspace reaches the backend API through the same WAF as the frontend. The dashed box is a dependency outside the team's own environment.
Keep in mind:

Network diagrams should be created for all environments, providing necessary information on all resources in all environments, as well as connections between them.

Data Flow Diagram

The data flow diagram shows the data flow of the solution. This should include all direct dependencies not part of the project, so that it is possible to understand where data originates and all the nodes it interacts with.

Data flow diagram for a development environment The data comes from two sources: the production-sql-01 database on separate hardware, where three views are in use, and the datalake-somedata-prod01 container in the company data platform. Both are loaded by ingest-factory-dev-01, which runs four pipelines. From there the data is written to the CurrentData and HistoricalData schemas in backend-dev-sql01. HistoricalData is read by Report01 and Report02 in dev-workspace, CurrentData by Report03. Sources production-sql-01 on-prem Views used v_get_all_production_data v_get_production_summary_12mth v_get_products_info Company data platform (dependency) Container datalake-somedata-prod01/ production-data-container Ingestion ingest-factory-dev-01 Pipelines Copy_production_data Copies production data Update_production_summary Updates the summary Refresh_products_info Updates the product index Copy_datalake_data Reads from the data lake Storage backend-dev-sql01 Schemas CurrentData HistoricalData Reporting dev-workspace Reports Report01 Report02 Report03
Example of a data flow diagram. It follows the data from source to report and names the views, pipelines and schemas actually in use at each step. That naming is what makes the diagram useful when a discrepancy has to be traced back.

IAM Diagram

An IAM-diagram describes where users originate, and the roles and permissions assigned to users, services and devices on the various resources.

IAM diagram for a development environment On the left are the identities in Entra ID: a service principal for Azure DevOps, the managed identities of Backend and ingest-factory, a developer and an application user. On the right is Dev Subscription with the resources backend-dev-sql01 and dev-keyvault, the resource groups Backend and Frontend, and production-sql-01, which runs on separate hardware outside the subscription. The service principal is Owner on the subscription and the developer is Contributor. The developer is also Key Vault Secrets Officer on dev-keyvault and SQL Admin on both backend-dev-sql01 and production-sql-01. The managed identities are Key Vault Secrets User on dev-keyvault and db_datareader on backend-dev-sql01. The application user holds a user role on Frontend. Entra ID Users and service principals Dev Subscription Subscription Owner Contributor SQL Admin db_datareader Key Vault Secrets Officer Key Vault Secrets User User role SQL Admin Service principal Azure DevOps Managed identities Backend, ingest-factory Developer Application user backend-dev-sql01 Azure SQL dev-keyvault Key Vault Backend Resource group Frontend Resource group production-sql-01 On-prem, outside the subscription
Example of an IAM diagram. Identities are on the left, scopes on the right, and every arrow is one role assignment labelled with the role name. Arrows ending on the edge of the subscription box are assigned at subscription level and inherit down to everything inside it; arrows ending on a resource apply to that resource only. The point is that no access goes undocumented.

Dependencies

This can also be drawn, but often a simple list is enough. This should contain all direct dependencies of the solution being developed, with a brief summary containing descriptions of what the team depend on.

  • On-prem database server production-sql-01
    • Uses three views maintained by the team
    • Data is imported via ADF
  • Company’s data platform, datalake datalake-somedata-prod01
    • Consumes datasets in the container production-data-container
    • Lineage is visible in Purview
    • Uses only datasets approved by the data owner

More Information