Some thoughts on Structuring modeling projects in Visual Studio Team Architect.

The success of using models [UML and non-UML] in the application lifecycle dependents deeply on how you’ve organized them, and with that also the success of the solution you are going to deliver.

Models [mainly the UML ones] are used for communication. Communication with different shareholders how the solution looks like and to discuss how the different concerns and needs find their way in the solution. But also to communicate with developers, testers, operations, designers and many more.


[A like this picture of different types of stakeholders, from the change management toolbox ]

Communication, Keep it simple.

The most important thing you have to think of when you want to communicate something with someone is to be clear..! With models this means; clear in language use, so people understand the models. Avoid jargon and overuse of big words.

As the poet William Butler Yeats once said:

William Butler Yeats

Not only be understandable in language but also be clear and self explaining in the organization of the models, so people can find their way in the solution. Just as the basic rules used when writing and article or book.

Organization Maintain a logical order or sequence. Paragraphs should deal with one subject. Logical transitions should be made within sentences and from paragraph to paragraph. Make sure introductions and conclusions are evident. Make it easy on the reader to see your point of view by guiding them logically down a path.

With this in mind, lets organize some thoughts how to structure the modeling effort.

I almost forgot one thing many people, organizations trying to accomplish with the use of models traceability. Traceability of requirements top–down and traceable from bottom-up. Traceability is an interesting goal, a hard to reach goal but we can keep it in mind will organizing our model structure.

The Default Modeling Structure

Lets call it default, because the most common way to group diagrams is in levels of abstraction [Business, Analysis, System and Implementation, see image below].  And within this grouping models are often divided in scenarios, userstories and components, subsystems, sometimes grouped by iteration [see analyses and system model].  Picture1

Having the models structured in this way makes it easy to understand at what kind, what level, you are looking. for example when you want to know the overall


meaning of the system under development, look in the Business Model folder. When you find the piece what’s interesting for you step one folder lower and look at a more detailed level in the analysis model. You can walk down till implementation level, the code and corresponding class diagrams. [with VSTA’s designer bus this should be even more easy]

You also see structures where the analysis model and system-design model are divided in scenarios grouped by iteration [I call it system-design model because the other part of the system model is the high level architecture/ software architecture, see image]. Grouping these two models together gives an easy way to find the meaning, requirements and the corresponding design of components, useful when you have a lot of components and subsystems with many functionality [also called vertical grouping].

Possible artifacts.

Possible, because every project is different and with every project we must think about the structure modeling method, what models are needed and even more important which models are useless.
The Business Model, meant to get business-driven requirements and set boundaries, is not always necessary. Within big companies with mature enterprise architecture skills this is often already defined and is the input for the project. [The Enterprise Architect and the Application ]. But, it’s still very useful to have this information in the solution and not somewhere on a portal, teammembers will have easy access to the “business / why this project” information. And the business models are input for the analysis models. Often used models are: Business Use Cases [Capturing business requirements using use cases], Business Activity Diagram [and-or state chart],  and Business Object Model [Class diagram]. When the Business model is in place [and additional information like a glossary], you can define the key usages scenarios for the project.  

The Analysis Model, captures more detailed requirements, user stories and/ or usages scenarios [depends on what methodology your team uses]. From the key scenarios found during business modeling, capture the more detailed use cases, activity diagrams and domain model. Just enough information to get an understanding how the high level architecture should be modeled in the System Model. Traceability between the business model and analysis model is easy. the same kind of diagrams are used and the information is just a bit more details in the system model than in the business model.

Core Architecture Design ActivitiesFrom the, kind of, requirements gathering models we get at the level of defining our system. The Application Architecture Guidance from the Patterns and Practices group gives a nice overview of this process [see image]. A must see is the video they made. Within the System Model there are two different models [or more] the first is the high level architecture which gives an overview of the system. Component diagrams are often used at this level and also the layer diagram [ the deployment diagram isn't available in VSTA but should also be used at this level]. This high level architecture sets the technical boundaries of the system from where the other parts are designed. I call it the System Design Model, this is where scenarios, requirements who need more designing because they are hard to understand, difficult to implement or some other reason are modeled. Also by using component diagrams, layer diagrams, class, sequence… you name it. so that’s the reason why I divided this system model in two parts.

The thick red line between Analysis model and System model is there because traceability between these two artifacts is hard, two different things get modeled [requirements versus system] and with different diagrams. A thing often done to validate the system design is replaying the key scenarios with a sequence diagram at component level. The Implementation Model is actually the code and the diagrams who live very near the code like class diagrams. As you can see in the Solution Explorer image I called this folder ‘Source’, because that's what we used to do. Also between System Model and Implementation Model a red line and hard to organize traceability for the same reasons. Although the layer diagram with the architecture validation capability makes it easier to get a connection between these two.

4+1 View

The 4+1 View is something everybody learns on school as a way to describe an architecture of a system. This view model designed by Philippe Kruchten defines it’s views based on the viewpoint of different involved stakeholders.

4 1_Architectural_View_Model

The scenarios [use case view] are the reason for the system and all the other describe the system, that's way the +1. You can structure your models based on this viewpoint model. Mapped on the ‘default’ structure described in the previous paragraph, it would look something like this; The business model and analysis model are the scenario’s. The system model can be mapped to the logical view, although i do think the logical view as described in the different books has a bit lower abstraction level than the system model as described in the previous paragraph. The logical view can be structured in a horizontal way and a vertical way.

Vertical and horizontal divisions
The application can be vertically divided into significant functional areas (i.e., order capture subsystems, order processing subsystems).
Or, it can be horizontally divided into a layered architecture distributing responsibilities among these layers (i.e., presentation layers, services layers, business logic layers, and data access layers).
[whitepaper [the pdf ] from Sparx]

In the example structure I divided it in functional areas. The process view together with the Logical view are at a conceptual level while the other two [development and deployment [physical]] are at a physical level. In the ‘default’ and in the example structure, the process and logical view are grouped in functional areas, you also can divide them in separate folders. The other two ‘physical’ views is the implementation model, although Visual Studio Team Architect 2010 CTP doesn't have a Deployment diagram [yet..? ]. The development view is the source folder in the example structure, because the class diagrams in team architect are coupled in someway [actually there are two different class diagrams within VSTA, the very tied coupled which is actually a visual representation of the code and the loose coupled logical class diagram from where you can promote classes to the physical level] with the sources. You could make a separate folder for the implementation model / development view and use that one for the logical class diagrams and put the physical class diagrams near the sources. Not a very clear structure, in that way you put the same information two different places.

Actually we made the ‘default’ structure in a 4+1 way. So, when the environment/ customer wants a 4+1 just change the names ;-). 


It is possible to make one big diagram in each model, one big use case diagram in the analysis model and one big class diagram in the system model. The pro is that you have everything, all the information together in one place, the con is you need a A-1 plotter and a big wall where you can put it on, beside this con there are many more cons than pros.


[not a class diagram, but a generated Web Service Software Factory servicemodel from a Amazon webservice, see this old post]

When there is just a single owner and editor of the diagram it can be done, one big diagram, beside it’s unreadable for the users. But, when there is more than one editor you get in to problems, merging problems. I change a reference to an object and somebody else removes that object… what should happen when both of use check in the diagram?  So, one big reason to breakdown your models is merging. Another reason close to merging is you must be able to change your diagrams in an easy way [ready for change]. Within one big model it’s first hard to find where you need to change something and second it’s even harder to find the dependencies. And I think when you breakdown your models, you also think about important architectural guidelines, like functional cohesion, ownership and loose coupling. For more key design principles, see the application architecture guid, Chapter 3 – Architecture and Design Guidelines.  

Some more Thoughts

To get the models and modeling content organized in a way so it’s understandable, simple and ready for communication is hard. Writing a book is hard, getting the structure of the book right is even harder, but getting it right for a software solution is even more troublesome, there are that many different dependencies you have to take in to account that there isn’t an one solution fits all. But not to get depressive, we can have a look at the most important ones and find a solution.

This image from the book “Getting Results from Software Development Teams by Lawrence J. Peters” gives a nice overview of the Modeling Method decision making.


The author described in this chapter also challenges in adopting a Modeling Method, interesting reading. One of the inputs for the modeling method is the type if system to be modeled.

Dependency; Architectural Style, [Type of System].

This is where the The Architecture Meta-Frame found in the Application Architecture Guidance V2 comes very helpful. It describes the most common application types and architectural styles, every type has it’s own pros and cons, but also every architectural style has it’s ‘preferred’ way of structuring the modeling files and projects.

An architectural style is a collection of principles that shapes the design of your application. Many of these styles overlap and can be used in combination. Architectural styles tend to be tied both to the application type and to the point in time in which the application was developed.

Because the Business Model and Analysis Model are a kind of solution independent there will be not much difference needed in the structure. [’Kind of’ because different architectural styles can result to different requirements]. The system and implementation models will have a dependency with the architectural style. For example a Client Server style solution often exist out of  database which runs on a server [or in the cloud] and some kind of client application type. The client application is most often divided in to layers. the requirements gathering models will probably stay the same but the system model will have additional diagrams, for example the logical data diagram and for sure the breakdown of the diagrams will be different.arch meta frame

In the client server example you will definitely have a client and a server part, where the server part is the logical data model and the database diagrams. With an N-tier architectural style you probably will break down the models in tiers [difference between distributed deployment, non-distributed deployment], while with a SOA style there are many separated services with some kind of layering and some kind of Business Process Model.   

Dependency; Team Organization.

There are team scenarios which influenced the structure of the models. The most simple team structure is just one team working on one project, see image below in this situation the default model structure can be used. Everything is available in one solution, every roll can access the information needed to do his job. 


As you probably notice I derived the model structure image from the TFS Guidance from the Patterns and Practices group. See this chapter of the guidance. I’ve added the modelprojects to it. When the system model contains an VSTA Layer Diagram we can validation if the refereneces between the projects defined in this layer diagram are the same as the real world.

It gets more complicated in larger projects where a partitioned solution structure is used [again see TFS Guidance]. Within the development department of an insurance company, for example, there are probably many teams working on different applications/ services or different versions of an application. Communication gets even more important when different projectteams have dependencies with other projectteams [image below and this post VSTA, the enterprise architect and the application lifecycle and this too old post Autonomous Develop Services for SOA Projects with Team Architect and Service Factory].

This large development project is divided in several solutions, because their is still one business demand there is just one business model in the master-solution, and one system model [the HLA part see first paragraph] that gives an overview of the structure of all the child-solutions and their relations. Probably [hopefully] during the breakdown is taken care of the architectural guidelines mentioned in the ‘breakdown’ paragraph [functional cohesion, ownership and loose coupling], so the child-solutions can have their own analysis, system [the lower part] and implementation models.


One project team opens his child-solution and want to start defining it’s implementation model, layers, components and classes, what kind of information do they need? first the analysis model to get information what should be build and second, the dependencies [the interfaces] with the other projects. This information is available in the master-solution but it would be inefficient when they also had to open the master-solution just to get a view of the relations. So, a better way should be when with the child-solutions also contains the two modeling projects [business model and system model] from the master-solution. A very easy way to accomplish this is with the add existing project menu-item. One big benefit of adding the business and system model to the child-solutions is that the elements used in these diagrams appear in the model explorer and can be re-used in the child models.

1 2

Master solution with all the child projects, the Business and System model named the High Level Architecture.

A child solution with at the right the child analysis, detailed system and implementation models… and the embedded master business / system HLA… which show up in the model explorer for reuse.

The very large project is actually a combination of ‘normal’ projects and ‘large’projects. Although the solutions which have an dependency are still troublesome and should be build in the order of dependency… see image form again the TFS guidance.


Dependency; Methodology.

CMM vs Agile… a big difference, see Agile Modeling for details.


pfff… don’t feel like typing any more, the story got a bit longer than I wanted... but will be continued, because this also opens opportunities for the Blueprints [see the posts I did with Edward]. 

One final quote:

The essence of "good design" is it's ability to be absorbed by a human mind. Design is "good" when it can be easily-learned.
Good design is about knowledge. We wrap it up in all kinds of terminology, but in the end it's about making smallish bits of software that are easy to understand on their own, and that fit together exquisitely to make things bigger than themselves, and that can still be as easily understood.
"Good Design" Means ...?

Comments (1) -

great article, thanks for your thought.

Add comment