Life of an application

A life is about choices. Architecture is about making best possible choices in context of current requirements and constraints. Requirements can be functional or non functional, and constraints limit our solution space. Guess we now that and writing yet another article about it would not be interesting. But every architect should document the reasons of important decisions that are made. This article will focus on how to do it in Sparx Enterprise Architect with reference to project requirements.

The reasoning

As an architect one needs to document important issues, possible solutions and reasons for choosing one of the solutions. There are various reasons to do it:

  • Reasoning that stood behind a choice will blur with time so the architect will not be able to precisely defend the decisions made
  • Architect may need to defend or just describe reasons for his decisions for various reasons like some other architect joining the team, client (or consultancy company hired by client) can have questions
  • Requirements and constraints may change in time and decisions may have to be reviewed. It would be easier to review decisions if we know why they were made
  • Architect may choose to leave project and someone may have to take over

I had experiences the last situation from both sides. Luckily, when I was leaving project developed for one of Polish banks I left my architecture log so my colleagues knew how to describe and defend the decisions. But imagine a poor architect that takes over a not trivial project and has to defend choices made by previous architect. Some may be questionable, some not, but living this poor guy without data on why this decisions were made we have.

Decisions can be kept in various places:

  • Some text files
  • Excel sheets
  • Case tools

Using case tool that is used to model requirements ha an advantage of keeping all data together and allowing one to do searches on data easily.

Sparx Systems Enterprise Architect is an example of such tool. Sparx Systems Enterprise architect is often used to manage requirements,  design the solutions architecture and to convey design to development teams. It allows quite a lot of project views and aspects to be modeled like requirements, physical and logical architecture, 4+1 architecture views, TOGAF models and a lot more. Using Sparx EA makes it possible to keep requirements and architectural issues log in one place and to create connections between issues and requirements. This allows us to partially or fully automate process of selecting issues that need to be reviewed if that is the requirement. As always this possibility is a tool and one should keep in mind that full automation in some cases or stages of the project can replaces with more agile, face to face interactions.

Using Sparx EA and UML Profile

To efficiently store architectural decisions in EA one should create a profile. It is possible to create an architectural decisions log without a profile, using one of other extension mechanisms of UML like stereotypes and profiles. Using profile gives us a better separation between model elements and this is the reason I like this approach. Creating UML profiles is described well in EA Docs so there is no need for me to repeat this information. Architecture decision log profile should contain four classes:

  • Architectural issues log – this stereotype extends package
  • Architectural issue – this stereotype extends package
  • Architectural context – this stereotype extends artifact
  • Architectural decision – this stereotype extends artifact
  • Architectural alternative solution – this stereotype extends artifact

Architectural issues log and Architectural issue stereotypes extend package in order to be containers for other elements. Architectural issues log will contain many Architectural issues.

Each issues will have it’s own packages in order to lessen the maintenance cost for Enterprise Architect model in the context of document generation. If we would keep them in one package then ordering the elements would be problematic, especially if later some new alternative decisions would be added.

Architectural issue will store description of the problem and a short title (we wont to keep the log simple). Architectural issue will also group architectural issue context, decision and alternative solutions. Each context must be connected via a trace relation to the requirements that engendered this issue.

Architectural context element will specify known constraints (both technical and non-technical) that limit possible solution space.

Architectural decision will contain reasoning on why the solution was chosen. This should be a short text as every alternative solution should contain advantages and disadvantages of a given solution that will give a good insight on each solution. This model allows to work with alternative solutions more easily, each solution has its dedicated element so they do not get mixed up making them harder to read.

Each Architectural issue will contain a number of Architectural alternative solution. Each solution alternative is independent solution option.

Architectural issues log is a package that will group various architectural issues.

Custom model search

When we have the profile in place we can create a custom search that will allow us to find the decision for which requirements have changed. Both elements have modification date so it is easy to track down issues that need to be reviewed.

We can do it in several ways:

  • Building a custom application that will use EA automation interface to search repository
  • Search the EA database (no the most elegant solution – in case EA db model changes the tool will also have to be updated)
  • Create a plug-in
  • Do a custom model search using EA extension features

Last solution is quite simple and thanks to the fact that it uses EA extension features user will work with EA only to manage Architecture Decisions Log.

Such query over EA model can be done in two ways:

  • With query designer
  • With sql queries

Second option is more powerful but a little bit difficult. There is a very good description on how to create such query on Bellekens blog. In our case we wont to search over objects with type ArchitectureIssue and look for those for which the requirements changed, so the query need to look like the one below:

What we do here is we simply search for all Architectural issues that were modified earlier than last modification of requirements that they were to address.

Good thing about this query is that is will work on most if not all databases supported by EA. In case if you find yourself using some DB vendor specific statements you can use #DB# macro supported by EA.

Columns and tables used:

  • t_object – this is a table that stores information about elements in model
    • ea_guid – UUID in EA model
    • name – name of element
    • Object_ID  – object identifier in EA repository
    • Object_Type – type of object (class, artifact, interface, etc.)
    • Stereotype – stereotype of this object
    • ModifiedDate – date of modification
  • t_connector – this is table stores elements about relations (also elements in model)
    • End_Object_ID – id of object at the end of relation
    • Start_Object_ID – id of object at the start of relation

Using this simple query we can quickly validate our model and see what needs to be reviewed.

If you want to find the column names meaning not covered in this query than please take a look at this Read Inside Enterprise Architect site.

Conclusions

Keeping project documentation together is important. Thanks to EA powerful reporting features and tools such as EA Docx we can generate documentation for the projects straight out of EA. We can create our own tools to cover features not included in EA. Architecture decisions are part of projects documentation, a very important part so they need to be included. Just remember to keep thing simple enough to document those decisions.