6.2 Architecture Documentation Part 2

00:00

and welcome back to Episode 14

00:03

off Cyber security, architecture, fundamentals,

00:07

architecture documentation, Part two.

00:11

In this session,

00:13

I would be covering architectural decisions what it is, how to put it together

00:19

and how to put all the previous work from the past sessions from Trent models to architecture design

00:27

into one document.

00:29

I know enough with some commercial tools that can help you.

00:35

So what is an architectural decision?

00:38

Well, from Wikipedia,

00:41

architectural decisions influence and impact the non functional characteristics of a system

00:47

each architecture decisions describes a concrete, architecturally significant design issue,

00:53

also known as a design problem designed, required

00:56

for which several potential solutions are options exists.

01:02

In short, you present why you made certain decisions and also the thought process behind coming to death decision. This is extremely important, as there's always tradeoffs in everything we do.

01:18

In some cases, we choose a certain solution because it's the only option we can afford. And debt is a valid architectural decision.

01:27

The last thing you one if someone coming in five years later looking at the design and wondering why such a decision was made and they questioned your competency,

01:40

those good to document all decisions and the rationale behind them so that future generations could understand how we arrive at those conclusions.

01:53

I think this is best illustrated with an example.

01:57

In this example, I'm showing I'm creating an architectural decisions on Thea Tent occassion method use for our application.

02:07

So in this case, we have the subject area being authentication,

02:13

and we state the decision that needs to be made in this case, which authentication I d. Do we use

02:22

Nick's? We try to articulate what is the issue or problem statement.

02:29

In this case, we would say we're unsure how many users have Facebook accounts that would use our system.

02:36

And if we use a local I d. How we manage and verify the local ID's,

02:44

these would scope out the problem statement for the decision.

02:49

In making any decisions, we usually have some assumptions. It is important to ST down all the assumptions made when making this decision.

03:00

In this case, the assumption made was that 80% off the target customers after Facebook account,

03:07

and we assume that Facebook would do a better job at idea verification than our internal team

03:15

mix. We try toe, understand what was the motivation that drives the decision in this case, the design principles off, having minimal steps for customer to create a lot on what's the motivation?

03:29

We also want to ensure that we document our completeness off thought. In this case, we are what is three alternatives,

03:37

and we could have used a Google I D or Twitter i d. As the lock and name.

03:43

In this case, the decision was made to use a Facebook i d.

03:47

Then we were right. The justification we use Facebook, i d. Simply because

03:53

the developers only know the Facebook a p I, and it's the only one that, comfortable with this is a valid decision,

04:00

as maybe the speed of delivery is important and they have no time to learn something else.

04:06

We would also need to list the implications or consequence off this decision.

04:12

In this case, customers who are like having a Facebook account will not come to your site or use your application.

04:18

And lastly, we tried to link other related decisions. For example, in this case, there might be another decision based on how uses are verified, and we'll link them together so that when someone reviewing the design could follow true all the related decisions.

04:38

This, in essence, is an architectural decision document. We would need to create one of these for every major decisions made along the way,

04:48

taking a step back, going back to the views in the previous session we want to talk about How do you actually document the views?

04:59

Well, the primary presentation is usually graphical. It's easy to convey the design in a picture rather than words. And English might not be the first language for many off your development team,

05:13

and we need to show what other elements

05:16

in the design and, well, it's a relationship between them.

05:19

We should also include the key that explains the notation, use and gift meanings to each symbols. Don't forget. The lines need meaning to.

05:30

It is also important to develop an element catalog, which explains all the element. Using the presentation,

05:38

we usually put this in a table or intellectual description.

05:42

If you're using a formal tool, this can be in

05:46

a

05:46

definition table in a database.

05:50

Sometimes some resource is have variables. Do not forget to Liston, for example, if he used a pull mechanism

06:00

list a number off instance in the pool

06:03

and any other parameters that is necessary to explain.

06:09

But the model

06:10

now do remember to attach the architecture decision for each of those views together with the design, so that they stay together for Sonny Buddy reviewing it

06:21

and for completeness. Also remember to relate it to another view, which is showing the same system or same processes

06:31

a stroke can imagine.

06:33

This gets very difficult

06:35

when your size grows and you have many components and many architectural decisions to be made.

06:42

It's very difficult to do this on paper or even discreet pictures like a physio or Paul Point. If you do use paper to record these, make sure you have a very good indexing system

06:56

and the spreadsheets. Pretty good tool for this,

07:00

but I believe it's worthwhile to invest in architecture to to help you manage your artifacts and the relationship.

07:09

Remember

07:10

to try to use standard formal notation like U N Rail to help in the communication

07:17

as the English language. It's not exactly very precise.

07:21

Another point to note ISS. Please start to create an asset catalog

07:28

to help re use architecture get easier over time if you have a control to help medicate a certain risk that control could be reused in another system with the same risks. So do take note of this.

07:45

As with everything else, no one knows everything. Be open to feedback

07:49

and update the document. The architecture document is a living document that needs to be updated when new information is uncovered.

08:00

Sometimes new technologies invented or new tricks are discovered, or some of your controls might be obsolete. ID.

08:09

So

08:09

make it a point to keep it up to date with the latest information and design

08:16

suspension earlier. Highlight

08:18

a few off the tools that are used by security architect CE.

08:24

All this ice server is a tool that supports the sub Sir Architecture.

08:30

The link here has a video to show how it would work and how it would help to have a central repositories off your artifacts.

08:39

Visual paradigm is another very popular tool used by architect CE.

08:45

It helps in linking all your diagrams together,

08:48

and it has out of the box support for many of the industry frameworks.

08:56

Another popular tool. This unit com System Architect. Just a formerly known as the IBM Rational System architect,

09:03

this two helps pull together all the different artifacts and let you drill down or go up to see all the different relationships within multiple systems.

09:16

While all of these twos have a learning curve,

09:18

it's actually more effective to spend the time to learn how to use a tour and document all your designs in a structured way

09:31

to go into more detail. Here are some good resource

09:35

in the IEEE Software magazine There was an article back in 2005 on architecture decisions, the mystifying architecture.

09:45

It has a pretty good explanation off how and why you should document your architecture decisions

09:50

and on slight share, I found interesting presentation on hard to do. Modeling off security architecture

10:00

might be a good video to see to compare with what you are doing currently.

10:05

So to wrap up this session,

10:09

I'll just briefly go to

10:11

what we discuss. We went through what is an architecture decision

10:15

and how to documented. Remember to use the template I provided to help you get started.

10:22

We also went through various tools that can help you

10:24

in the absence off tools. Please take care to index your documents and create relationships.

10:33

It can be pretty confusing once you grow to a certain size?

10:37

No.

10:37

In the next session, which would be the last session in the series, I would go through a case study

10:43

on how security architectures apply. So if you have the time, please join me in a next session.