artITecture

**** Click here to download the full example ****

after interest in the last post on architecture diagrams I am writing this description of the architecture diagram notation I have been using for several years.  This format has stood me in good stead for a number of large multi year projects with budgets from $10 to $50 million a year upwards.  In my current role as Chief Architect of the second largest project in IBM Globally we have a project budget in the half billion dollar range, we have hundreds of components and interfaces and the diagramming technique explained below is the one which I have enforced throughout the project, we successfully delivered our targets in 2007 and are on track for this year. It works. It scales. I do not know of any well thought through alternative. Any suggestions for improvement are welcome! I have also provided a download of the example discussed here – Click here to download the example set of Architecture Overview Diagrams – this also includes the additional information I recommend goes with the diagrams.

Example Diagram

I will start off with this relatively simple example (click to enlarge)

This architecture shows an SAP system communicating to a number of other systems. Each rectangular box represents a component and each component is uniquely numbered for ease of reference both when talking about this diagram but also when you create other artifacts you can reference the component using this number. The arrows shows the existence of a data flow between the systems, and again each data flow is uniquely numbered for ease of reference.

Level of Decomposition

Just a note here, when you create Architecture Overview Diagrams you will have to choose the level of decomposition. Look at the SAP box for instance – SAP is made up of many components like the database, SAP GUI, SAP NetWeaver, SAP Portal, etc. For the purpose of this overview diagram is simpler to abstract SAP into one box although really is has many components of interest. I have chosen this level of decomposition for the specific purpose of this diagram. If you abstract components like this you should consider adding another diagram which decomposes these more complex components to a further level of detail down. Have a look in the example presentation with this post. I have a separate diagram just to describe the SAP stack and which SAP components are used. On these kinds of diagrams you should not need to decompose to too fine a level of detail. If you have classes, and operators you are at too low a level for this kind of diagram, that is when you should switch to other diagramming techniques like UML.

Component Types (click to enlarge)

The different colours of the components do have a meaning and each box should be given a meaningful name.

The first box type in dark blue box is a component which is owned and is specifically part of your project scope (i.e. you own the deployment or change to this component), this maybe new or it could be a change to an existing component.

The second box type in grey is a component someone else owns, but no development is required at the other end of the to allow the transfer the data. This is often the case when you develop an interface which fits exactly the format which the other party is expecting without alteration, typically when an integration already exists and this new system is simply replacing a direct copy of what was already there. Small configuration changes might be necessary at the other end to accept the data from your source but this is assumed to be trivial. The implication of no development is that the integration should be relatively straightforward particularly from a project management point of view since the dependency on the other party is not significant.

The third type in light blue is where the other party does need to change and develop something to either send or receive data which was never sent or received before, or an alteration to the integration method. The implication here is the dependency between your system and the other party is significant. Their implementation schedule will need to match your dates for system integration, user testing and production deployment and production cut over.

The last type in light blue with a red surround is a component which sits outside the firewall, all the other component types are assumed to be with your internal network. This is important because the security necessary to talk to external system is often much tighter than communicating with other systems on your internal network.

Arrow Notation (click to enlarge)

First of all the direction of the arrow is important. It show the logical flow of the data.

The solid arrow is a direct flow of data. This is always automated, and alway system to system. The method of exchange is not explicitly described and further explanation will be required. If you look at the example deck the interface mechanism has a textual description and the method of transport. It could be any number of methods like ftp, MQ, JMS, REST, HTTP, SOAP, etc.

The dashed arrow is an indirect flow of data. This will require biomechanical automation (a human) to complete. Typical examples are uploading a spreadsheet or running and exporting a report which is then sent somewhere.

Lastly the red circle is used to show who is the initiating the transaction. The direction of the arrow shows the logical flow, but not who starts the transaction.

So in the first example the data is flowing from System A to B, but System B is the system which initiatives the data flow. This could be calling a service call, or an ODBC connection to System A made by System B to retrieve the data.

The second arrow shows data flow from System A to system B, and it is System A which starts the transaction. A Message (MQ, JMS, etc) would be an example of this, as is a batch interface where System A create the batch interface and sends it to System B.

Other Notation (click to enlarge)

These two boxes are used to uniquely number every single component and interface in the diagram. Diagrams may span several pages, uniqueness should be preserved across an entire architecture.

One improvement I will create to a colleague, Steve McKim, is when a component acts as a passthru, like MQ, or an ftp server label the boxes 6a, 6b, etc. This makes the diagram much easier to understand when the same data is flowing through multiple components.

Diving into the Example Diagram

Lets now take a couple of interfaces from the example diagrams and explain them, the first is generating a message from SAP and passing it to Websphere Message Broker

So you can see we have three components, and 2 interfaces. SAP generates a message and send the message to MQ. MQ is simply a pasthru and automagically send this to Websphere Message Broker. You can see the use of the 6a/6b notation on the interfacing number. The data is unchanged by MQ so it makes sense to show that the data from SAP is being moved to WMB unaltered.All of the arrows are solid so all of this is automated. Since this is a messaging model, SAP initiates the data flow to MQ, and MQ in turn initiates the data push to WMB. for simplicity I have left off what WMB does then. WMB is IBMs heavyweight messaging solution (ESB) so you can safely assume this does allsorts of data transformations, logging, and connections to allsorts of systems via any number of protocols.

The diagram itself is not sufficient to explain everything to the inquiring mind. Why SAP is generating this message is unexplained, how does SAP connect to MQ? SAP does not have native MQ connectivity nor does it generate MQ headers automatically so how is this done? All of this kind of thing needs to be covered in the detail documentation. In IBM and ITIL language this is a Component Model this is somewhat akin to good old internal and external design documents. I would also advocate proving a short explaination with the diagram and I have provided this in my full example.

The second example is a less clean indirect integration.

In this example a spreadsheet is created or updated somehow from SAP. The use of the dashed line indicates this is only partially automated. In this case a user is exporting a report into a spreadsheet possibly onto a server (more than likely their laptop/PC) and then using that spreadsheet as the data source for a Lotus Notes database. They are probably using an Agent in the Lotus Notes database to find and import the data.

Just the same as the first example, the diagram does not explain all the detail, but it does communicate the general data flow and you can make reasonable assumption about what is happening. Further detail is needed to fully explain the flow, what is happening and why. The detail must also cover other considerations such as how the spreadsheet is secured if it contains confidential information.

And Finally…

Remember that these diagrams are a communication method. In any good communication you know your audience and you tailor your communication to them. This notation is very good for communication with other architects and developers at a project level but also at Architecture Review Boards. I have also used these with auditors who often have technical leanings. This format probably isnt what you want to show an executive

I said it a few times already these diagrams are useful in their own right but you will need further detail documentation to explain more about what is happening and why, particularly to developers. A crucial piece of the notation is the unique numbering format which allows you to tie any given component or interface shown in this diagrams to the detail documentation.