Repositories

Using Enterprise Architect as a central repository of all organization-related information could lead to storing a massive amount of data in one place. This is why it is not sufficient to simply start filling the repository with elements and models, but it should be first outlined how the information will be structured and organized. There is no universal approach, so what is presented in this chapter is one of the possible ways.

Documentation and Working Repository

The repository structure presented in this section expects that there are two Enterprise Architect repositories created:

1. The documentation repository contains a snapshot of the current state of the organization. It is used for describing how the organization works at the moment, and if no change happens, the documentation repository is read-only.
2. The working repository describes the future state of the organization. In other words, it includes changes. For example, if the organization decided to implement a new system, its specification will be included in the working repository. This way it is possible to separate what the organization currently has from what it is going to implement in the future.

NOTE
It is also possible to take the simpler approach and stick with a single repository. In this setup, the documentation process is more straightforward as all changes are put into the same repository, so no synchronization between the repositories is needed. However, since the as-is documentation is stored in the same place as the planned changes, it may not be possible to tell how the current state looks. The future changes are incorporated directly to the as-is documentation, and the reader always sees just the future state.

The approach that uses two repositories is naturally slightly more complicated than the single-repository approach. As a result, it also requires more discipline. To get all benefits which stem from using two repositories, several rules must be followed to prevent the documentation process from being confusing:

1. Changes are never done directly to the documentation repository. Each element or diagram is first changed in the working repository, and after the change is released, it is transferred to the documentation repository. The reason is to separate the to-be state from the as-is state and to keep the documentation repository in sync with the real state of the enterprise.
2. Elements that represent the already existing artifacts are included in both repositories and share the same GUID (unique id across repositories). Migration of the elements from the working repository to documentation repository could be done using the EA's built-in Export/Import feature or via the middleware. Both ways will preserve the GUID of the migrated elements and diagrams.
   
3. The working repository is a mirror of the documentation repository, plus it includes future changes. When all changes are released, the changes are transferred from the working repository to the documentation repository. Until a new change is made in the working repository, the two repositories are in sync.

Repository Structure

The arrangement of the repository contents structure will be different for a big corporation and for a midsized software vendor company. Corporations typically operate dozens of systems and simultaneously change the legacy systems and implement the new ones. Therefore, corporations are interested mainly in knowing a big picture of their enterprise architecture, including the systems, business functions, or processes.

Software companies, on the other hand, do not need to understand all business domains and all systems that their customers possess. They are mainly interested in the aspects which influence or are directly related to the solution they were asked to work on.

1. Corporation

Corporate EA repository structure reflects the organization's main areas of interest: business, IT and projects. Business and IT packages contain a description of the business and IT architecture. Projects include changes the company has already implemented or those that are being currently analyzed.

Documentation Repository

Business Architecture package describes the main areas of the company's business. Since each business is different, the structure cannot be prescribed. In most cases, it will be organized by business units, products, or services.

IT Architecture lists the company's IT systems and applications, their components, and the relationships between them. Each system is placed in a separate package which includes all related artifacts that describe the system. The system itself is represented by a UML component, also located in this package. Both the package and the component are named as the system.

Projects package is an archive of the projects which have already been implemented. The reason to include them in the documentation repository is the need to trace the systems and processes changes to projects to keep the information about who implemented the change and why. The ability to trace an organizational component change to the particular project greatly simplifies identification of why the change was done, when and by whom.

Small Enhancements: The Projects package includes only projects that have a rather big impact. Small enhancements which only adds a new feature or fixes a bug are included in the package Changes under the given system.

Working Repository

The working repository contains specifications of the future organizational changes and the overall state of the organization after the changes are implemented. Changes are realized within projects which can create or modify one or many enterprise components - for example, the project updates two legacy systems, implements a new application, and changes three business processes. The example of a project is shown in the following picture:

The project includes all information gathered during analysis, such as requirements, knowledge about the business domain, business rules, terms, and so on. The second part describes changes to the individual enterprise components. In this case, it is two systems. Each component holds both analysis and design artifacts, so it is ok that it includes high-level features as well as low-level implementation details.

2. Software Vendor

In case of the software company, the repository structure reflects the stronger orientation on projects and products rather than the need to describe the enterprise architecture of the company. Although software vendor also needs to understand how the customer's business works or how their systems are integrated, the scope of information is always limited to the context of the change the vendor is expected to deliver.

Documentation Repository

The structure of the documentation repository depends on whether the company develops more independent projects for various clients or if it focuses more on products deployed at multiple customers.

Project-oriented

The project-oriented software company develops custom software for a single customer. The repository tree reflects this and includes a list of projects grouped by customers as multiple projects could be implemented for a single customer:

Each project package contains a full set of artifacts and diagrams documenting a particular solution. It also includes processes, glossary, and other business artifacts, which are important to understand the business behind the project. Besides, there is also the Business Architecture package, which may optionally describe the customer's business and could then be reused by the teams implementing different projects for the same customer.

Product-Oriented

Another type of software companies is product-oriented companies. These companies have a couple of products in their portfolio, which they implement for various customers. Thus the structure of the documentation is based on products:

Each product package describes the "core" functions of the solution, which are common for all implementations. Then, each custom implementation (described in package "Implementations") includes variations that were specifically implemented for the concrete customer.

Working Repository

The working repository of the project-oriented company consists of the projects which are currently being analyzed or developed for the different customers:

It could also contain a list of already implemented projects for the current customer (the structure is the same as for the documentation repository). The reason why it may be handy to have it here is that the projects under development can be integrated with the already implemented projects or could share some of their parts. It is analogous to the "IT Architecture Package" included in the corporate working repository.

The structure for the product-oriented companies is very similar, it just reflects the focus on products rather than on projects: