Definition and Documentation of Software Architectures

This paper discusses the work of the software architect by describing a software architect’s concerns and the documents that a software architect should produce. It proposes a definition of software architecture and discusses archtectural design criteria based on the idea that every architecture is expected to meet a specified set of goals. We start with a discussion of the meaning of “architecture”, then discuss the goals of an architect, proceed to what’s needed to achieve those goals, describe ways of documenting architectural design decisions, and finally discuss how to determine how well the design goals have been met for any given architecture. 1 An Analogy: Traditional Architecture When buildings are designed, constructed, or renovated, key designers, designated as “architects”, have a broad range of responsibilities. An architect prepares initial sketches of the building, showing both external appearance and internal layout, and discusses these sketches with clients until all concerned have agreed that what is shown is what they want. The sketches are abstractions; they omit many details of the building. After the clients and architects agree on these abstractions, the architects prepare, or supervise the preparation of, much more detailed drawings as well as associated textual specifications. These drawings and specifications describe many “nitty gritty” details of a building, such as plumbing, siding materials, window glazing, electrical wiring, etc. On rare occasions an architect simply hands the detailed plans to a builder who completes the project in accordance with the plans. For more important projects, the architect remains involved, regularly inspects the work, and may propose changes or accept suggestions for change from builder and customer. When the architect supervises the project, it is not considered complete until the architect certifies that it is in substantial compliance with the plans and specifications. We employ architect(s) to assure that the design (1) meets the needs of the client, (2) has conceptual integrity, i.e. that the same design rules are used throughout, and (3) meets legal and safety requirements. An important part of the architect’s role is to insure that the design concepts are consistently realised during the implementation. Sometimes, the architect also acts as a mediator between builder and client. It is important to note that a building architect is concerned with far more than the facade of the building and that the architect’s decisions constrain the builders. However, it is even more important to note that the architect does not make all of the design decisions. The architect specifies certain essential properties of the design, but project supervisors, carpenters and others often have to make further decisions while completing the construction. There is often some disagreement about which decisions are in the realm of the architect and which are left to others, but it is always clear that the architect makes the major decisions, including all that can affect the usability, safety, and maintainability of the structure.