Artifact Deliverables

Artifact Deliverables

Workload Architecture Design Spec (WADS)

The documentation is considered a compliation of the items below that aligns with the constraints of the functional, technical, business requires, and business goals. It includes all decisions that were made in the ADR or perhaps a reference link to them as well as any POCs, Reviews from security, compliance and others. It should also include the RACI chart that shows the responsibilities.

For more information about design specs

Architect Decision Record (ADR)

Top Helpful tips

Process Approach

• Be consistent and methodical in your approach at all times
• Only provide consise assertive facts

Communication

• Make sure to share the decisions everyone and inform them at all times
• Meeting notes and decision logs should be stored where everyone can access (read) them at any time

Assimilating Data

• Make use of the MADR ( Markup Architect Decision Record templates) on important architecture and design decisions
• Record all meeting notes for any conversations, the topics and outcomes, who participated.

Managing Expecations

• Make sure DoR and DoD are well defined
• Stay away from anti-patterns and anything that causes undeterministic choices

Azure ADR
Template Gitrepo Source

Diagrams

While I do prefer Visio to make my designs, it might be eventually an easier for future maintainance to use digraming that can automatically be generated and updated such as diagram-as-code.

BlackBox Scenario

If you are coming onto a customer's site that has no documentation what-so-ever and you need to know how their Azure cloud architecuture is laid out at a high-level, then you should use this tools

ARM Viewer for VS Code

This tool creates a diagram based on the ARM template and while it might not be as detailed as you want, it IS a good starting spot for a team coming into a black-box situation.

Diagram Tools

Visio is great for organizations that their architecture doesn't update much, but as your organization evolves, so does the architecture. It may be wise to obtain a common flow to keep track with the architecture so it will always be to date.

• Diagram-as-Code:
  • Uses python: https://diagrams.mingrammer.com/ - a python tool that uses Graphviz libraries that you can use locally or in a pipeline. In my opinion, it is easy to learn, looks really good to use cloud partner icons such as Azure, AWS or Google, but it has limitations for icons on edges and clusters for me.

Diagram Types

This is a shorter explanation of the ones on from Azure and other places.

• Architecture design diagrams (AS-IS & TO-BE)
  • High-level system designs
    • Use these when in need to communicate with stakeholders to bridge common understanding
  • Block diagrams
    • Use these when you need to refer to internal generic functionality of components and their relationship
  • Component diagrams
    • Use these when you are designing with specific technology components and the relationship with other specific components.
  • Deployment diagrams
    • Use these when you need to explain deployments from custom software, commerical (COTS) and the infrastrcuture and how it's used.
  • Data flow diagrams
    • Use these when you need show how data moves through the system. This is incredibly helpful when you need to trace how data moves from one system through the other to find issues.
  • Sequence diagrams
    • Uses these for communication between your systems and users. This is strong for HTTP call illustrations, however, if you need process sequence, you should use others and label them 1,2,3,4,etc.
  • User-flow diagrams
    • Use these and label them 1,2,3,4 as the user interacts with the system and components.
  • Entity-relationship diagrams
    • Use these when trying to show the relationship between the data and the storage system (database). The goal is to define how the data relationship and how the data will be used.
  • Network diagrams
    • Use these when you need to show the components, workload and it's environment based on security, landing zones, PoF (points of failure) and ingress/egress areas with throughput expectations if necessary.
  • State diagrams
    • Use these when you need to understand the state of an individual component and the conditional flow between each state.
  • Flowchart
    • Use these when you need communicate how a process should work, all choice directional paths that need to be made and any and all failures. This helps users get on the same page. If communicating this to stakeholders, you might want to have a high flow chart to ease the audience into it, and then provide a deeper illutration help guide them to a better understanding.

POCs

TBD

Reviews

TBD

RACI Charts

TBD