Building Architecture Diagrams

Introduction

To be able to build a thorough and clear architecture diagram, you must first understand the process. Most processes can be broken down into one singular concept, “the movement and transformation of data.” The problem is that simple concepts are obscured behind preconceived notions and the customer’s focus on their solution. Our job is to see through those steps to see the core of what we are doing, then translate that for a developer into a solution.  

Background

This methodology has been tried with customers from the scale of small business to large corporations. This has been executed with a clear simple processes that are merely inputting data into a form, to extracting complex data from invoices.  

The goal is to enable you to be able to execute a plan for any size process or problem to solve. 

The process

This article is under the assumption that a process has been identified. This process should have a clear beginning and end. Provide that both of those key steps are known before you start.

Make sure that you have either: 

1. A PDD

2. A SME(s) able to demonstrate the entire process from beginning to end

3. Recordings of the process from beginning to end

Pre-analysis or how to set expectations

Take time to have a high-level understanding of the process. What is the customer’s goal? Why is this helpful for them? These are questions that can help empathize with the customer’s needs and  look clearly at the ROI.  

Review these details (These should be documented in the PDD, communicate any gaps): 

• How long does this process take? 

• How often is this process completed?

• How much is processed in this process?

These are questions that can help with the next stage of building the architecture. Sometimes you can identify patterns during the analysis stage. Do not be concerned if you can’t identify patterns during this stage, pattern recognition will happen with experience.   

Analyzing

The first step is to have the tools necessary to take notes: 

1. OneNote – my preferred tool

2. Notepad

3. Pencil and Paper — not recommended

The PDD can often be overwhelming. The goal is to focus on the problem before you. Remember the core concept: “the movement and transformation of data”. 

Here are the questions to have in mind:

1. Where is the data? What applications are you interacting with? 

2. When is the data extracted?

• All data should have an input and an output.

• The input and output can be the same or different applications

• Hard-coded data: this is acceptable, note the value and note when's needed

3. Is the data transformed?

• Keep track of when all needed pieces for transformed data is acquired

•  Knowing when data is transformed can be determined in step two

4. How will we test this?

•  Is there a test environment?

•  What data examples would be helpful to validate branches? 

Mindset

Throughout writing out this information, you'll likely encounter inconsistencies. You might find that you are inputting information into an application that you have never extracted.   Ask yourself:   Where is this data come from?   Is it static?   Did it need to come from a previous step?   Was the data transformed by the Application?   How will we test this? 

Know and document the answers to those questions.   

Deliverable from analyzing

To simplify this process, you can use the following outline: 

When walking through the process step by step, you should be able to identify this information.   See past the UI and focus on the data.  The UI is merely “organized presentation of data” 

Application

Type 

We work day-by-day with many types of applications. It can be a UI application, a website, an API, a database, an Excel file, or a PDF. This list is not limited but ensure you can identify and name an application.  Access  SSO, MFA, integration, and username/password are a few different ways access may be required. If you are struggling to document this. Work with the SME to access the application yourself. Write down clearly the steps required to get access to the application.  This may include Citrix, remote sign in, stepping through multiple applications.  Prod vs test  Identify if the link provided is a production or test. If it is production, have the conversation to determine if a test environment is available. Take note the data being extracted. Having an example of the data extracted/input can help identify risks at this stage.

Input/output data Best practices  Started considering naming conventions. Are you using the same identifier for the data throughout the process?  Common risk identifiers  1. PII: does this need encryption? Examples: social security number, birthdate, firstname, lastname. 

2. Large objects: where will these be stored? Examples: files, images, JSON

After analyses

This is still part of the analysis stage of a process. We are not quite to the step of building the architecture diagram. It is common for information about the data to be missing. Do not be alarmed. This is a common flow.  Handling missing data steps  Upon reviewing the process, identify missing details about where data is coming from or where it is going. Make sure this information is documented and available before moving forward. These inconsistencies are clear when data is being input, but never extracted in a previous step.  Ask the following questions:  

1. Did you miss something?  2. Ask the BA  3. If a BA isn't available, communicate directly to the SME 4. If a more than 10% of the information is missing, communicate delay to your PM

Application details

Note application information. At the end of this analysis, know exactly what applications are being accessed and how. This is a key point to make sure that the specifics are known for development and production.  Here is a common methodology:  1. Communicate an application-access tracker to your PM or customer PM

2. Make sure access is provided or provisioned for all the applications identified: provisioned for developers and for production 

Conclusion

At this point, all the information needed to create a complete diagram, is documented. The core concept will be: “the movement and transformation of data.” Any gaps that exist in the process should be identified and understood.   For the next step, we'll be breaking this down into patterns and a solution. Recall the pre-analysis. We'll be going back to the goals of the customer and identifying a method to achieve those goals with the amounts of data.