Repositories

Using Enterprise Architect as a central repository for all organization-related information can lead to storing a massive amount of data in one place. This is why it is not enough to simply start filling the repository with elements and models; first, you need to define how the information will be structured and organized. There is no universal approach, so what is presented in this chapter is just one of many possible ways.

Documentation and Working Repository

The repository structure presented in this section assumes that two separate Enterprise Architect repositories are created:

1. The documentation repository contains a snapshot of the current state of the organization. It is used to describe how the organization operates at the moment and, as long as no changes occur, this repository remains read-only.
2. The working repository describes the future state of the organization. In other words, it includes planned changes. For example, if the organization decides to implement a new system, its specification will be placed in the working repository. This makes it possible to clearly separate what the organization currently has from what it plans to implement in the future.

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

The two-repository approach is naturally a bit more complex than using a single repository. As a result, it also requires more discipline. To get all the benefits of using two repositories, several rules must be followed to keep the documentation process clear and organized:

1. Changes are never made directly in the documentation repository. Every element or diagram is first updated in the working repository, and once the change is approved and released, it is transferred to the documentation repository. This separates the to-be state from the as-is state and keeps the documentation repository in sync with the actual state of the enterprise.
2. Elements that represent already existing artifacts are included in both repositories and share the same GUID (a unique ID across repositories). Migrating elements from the working repository to the documentation repository can be done using EA's built-in Export/Import feature or via middleware. Both methods preserve the GUID of the migrated elements and diagrams.
   
3. The working repository acts as a mirror of the documentation repository, but also includes future changes. When all changes are released, they are transferred from the working repository to the documentation repository. Until a new change is started in the working repository, the two repositories remain perfectly in sync.

Repository Structure

The layout of the repository content will differ significantly between a large corporation and a mid-sized software vendor. Corporations typically operate dozens of systems, simultaneously modifying legacy systems and implementing new ones. Therefore, corporations are mainly interested in seeing the big picture of their enterprise architecture, including systems, business functions, and processes.

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

1. Corporation

A corporate EA repository structure reflects the organization's main areas of interest: business, IT, and projects. The business and IT packages contain descriptions of the business and IT architecture, while the projects package includes changes the company has already implemented or those currently being analyzed.

Documentation Repository

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

The IT Architecture package lists the company's IT systems and applications, their components, and the relationships between them. Each system is placed in a separate package that includes all related artifacts describing that system. The system itself is represented by a UML component located within this package. Both the package and the component share the name of the system.

The Projects package serves as an archive of projects that have already been implemented. The reason to include them in the documentation repository is the need to trace system and process changes back to projects, keeping track of who implemented the change and why. The ability to trace an organizational component change to a specific project greatly simplifies finding out why a change was made, when, and by whom.

Small Enhancements: The Projects package only includes projects that have a relatively large impact. Small enhancements that just add a single feature or fix a bug are included in the Changes package under the given system.

Working Repository

The working repository contains specifications for future organizational changes and the overall state of the organization after those changes are implemented. Changes are delivered within projects that can create or modify one or many enterprise components—for example, a project might update two legacy systems, implement a new application, and change three business processes. An example of a project structure is shown in the following picture:

The project includes all information gathered during analysis, such as requirements, domain knowledge, business rules, terms, and so on. The second part describes changes to individual enterprise components (in this case, two systems). Each component holds both analysis and design artifacts, so it is perfectly fine for it to include high-level features alongside low-level implementation details.

2. Software Vendor

In the case of a software company, the repository structure reflects a stronger focus on projects and products rather than the need to describe the overall enterprise architecture of the company. Although a 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 independent projects for various clients or focuses on products deployed at multiple customers.

Project-oriented

A project-oriented software company develops custom software for individual clients. The repository tree reflects this by showing a list of projects grouped by customers, as multiple projects can be implemented for a single client:

Each project package contains a full set of artifacts and diagrams documenting that specific solution. It also includes processes, a glossary, and other business artifacts that are important for understanding the business context behind the project. Additionally, there is a Business Architecture package, which can optionally describe the customer's business so it can be reused by other teams working on different projects for the same customer.

Product-Oriented

Another type of software vendor is a product-oriented company. These companies have a few products in their portfolio which they implement for various customers. Therefore, the documentation structure is built around products:

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

Working Repository

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

It can also contain a list of already implemented projects for the current customer (using the same structure as the documentation repository). Having this here is useful because projects currently under development might integrate with already completed projects or share parts of them. This is similar to why the "IT Architecture Package" is included in the corporate working repository.

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