Creating Architecture Descriptions (ADs)

Technique · Chapter 12

What an architecture description is

An architecture description (AD) is a work product that expresses and communicates an architecture. The architecture itself is distinct from the artifacts that describe it, so one architecture can be captured by several different artifacts.

An AD:

• Identifies the stakeholders (users, administrators, domain experts, business analysts, product owners, management, development team) and their concerns.
• Addresses concerns such as system goals, the architecture’s suitability for those goals, its ability to meet quality attribute scenarios, ease of development/maintenance, and risks.
• Consists of one or more architecture views, each addressing different stakeholder concerns.

Architecture views

• A view focuses on a specific structure (or structures), letting the architect document and communicate one manageable piece at a time.
• Which views and how many to create depend on the documentation’s goals and audience — there is no definitive list and no fixed number.
• Views cost time to create and maintain, so add a view only when it provides benefit: never insufficient, but never excessive either.
• During design, capture informal sketches (structures, elements, relationships, patterns used) as a record; they later become the basis for the formal views.

Notations by level of formality

Notations differ mainly in formality. More formal ones cost more effort to create and read but reduce ambiguity and can drive tooling/code generation. Choose based on purpose, audience, your familiarity, and available tools.

Notation	Semantics	Analysis / code-gen	Best for
Informal	Natural language, ad-hoc conventions, general-purpose tools	None	Non-technical stakeholders, management, communicating scope
Semiformal	Standardized notation, semantics not fully defined	Some analysis; potential code generation	General modeling (e.g., UML)
Formal	Precise, usually mathematically based	Full syntax/semantic analysis; automated code-gen	Rigorous specification; poor for non-technical audiences

• Formal notations include architecture description languages (ADLs) — formal expressions used to model an architecture.
• AADL (Architecture Analysis and Design Language): models hardware and software, describes runtime architecture, generates docs/code.
• SysML (Systems Modeling Language): general-purpose graphical modeling maintained by the OMG; a subset of UML. Reuses UML’s use case, sequence, state, and package diagrams unchanged; modifies activity, block definition, and internal block diagrams; adds new requirement and parametric diagrams.

Including design rationale

• An AD should record the design rationale — the reasons and justification behind decisions (introduced in Architectural Drivers / Documenting the Software Architecture Design).
• Without it, the “why” is lost and even the original decision-makers forget the details over time.
• Record only architecturally important decisions; it is also useful to note why alternatives were rejected or why some decisions were deliberately deferred.

UML overview

UML is a general-purpose, standardized, widely understood modeling language. It has two modeling types:

• Structural modeling — static structure and relationships: class, component, package, deployment diagrams.
• Behavioral modeling — dynamic behavior over time: use case, sequence, activity diagrams.

Class diagrams

Show classes (attributes = state, operations = behavior) and their relationships. A class is a rectangle with up to three sections: name, attributes, operations.

• Visibility (grant only what is needed): + public, # protected (type + subclasses), ~ package, - private.
• Association — a semantic relationship, drawn as a solid line. No arrowheads = unspecified/bidirectional; open arrowhead = one-way navigability.
• Aggregation — hollow diamond; child can exist independently of the parent (Car has Tires, but a Tire survives without a Car).
• Composition — filled diamond; child cannot exist without the parent (a Room cannot exist without a Building).
• Multiplicity (cardinality): 0..1 zero or one, 1 / 1..1 exactly one, 0..* or * zero or more, 1..* one or more.
• Dependency — dashed line with open arrowhead; a weaker supplier/client relationship (e.g., a parameter or return type), where changes to the supplier may force changes to the client.
• Generalization/specialization — inheritance; hollow triangle nearest the base class. Generalization abstracts common members into a superclass; specialization derives subclasses (an “is-a” relationship).
• Realization — a class implements an interface; hollow triangle on a dashed line, triangle nearest the specifying element. Interfaces are marked with a stereotype (name in guillemets), one of UML’s extensibility mechanisms.

Component diagrams

Detail structural relationships between components (“wiring diagrams”). They expose the interfaces between components, identifying replaceable parts, reuse opportunities, and work that teams can build independently once an interface is agreed. Provided interfaces = “lollipop” (circle); required interfaces = “socket” (half circle). Components can nest. Depends on coding to interfaces, not implementations.

Package diagrams

Packages group elements and provide a namespace; package diagrams show dependencies between them, easing reasoning about large systems. Beyond standard dependencies they model package import (reference members without fully qualifying) and package merge (one package extended by another’s contents). Classic example: a layered application where Presentation → Business → Data, all depending on a Cross-Cutting package.

Deployment diagrams

Show physical deployment of artifacts (source files, binaries, scripts, DB tables, documents) onto nodes (computational resources, drawn as 3D boxes). Node types:

• Device — physical hardware (server, laptop, phone), can nest.
• Execution environment (EEN) — a software container within a device (OS, JVM, Docker container), can nest.

Use case diagrams

Use cases are brief text describing system behavior in response to actors (a role: person, organization, or external system). Actors support generalization (hollow triangle toward the ancestor). Diagrams show actors, use cases (ovals), their associations, and a system boundary box delimiting scope — useful for tracing functional requirements.

Sequence diagrams

Model how components interact and in what order (a type of interaction diagram; also event diagrams). Elements:

• Lifeline — object/class as a rectangle with a descending vertical dashed line; time flows downward. Named objectname : classname (underlined).
• Activation box — on a lifeline, showing when an object is performing a task; length ≈ duration.
• Messages — solid line + solid arrowhead = synchronous (sender waits); solid line + lined arrowhead = asynchronous (sender continues); dashed line + lined arrowhead = reply/return.
• Loops — box labeled loop with a guard, wrapping the iterated fragment.
• Optional flows — box labeled opt with a guard; executes if the single condition holds.
• Alternative flows — box labeled alt; multiple guarded fragments separated by dotted lines, only the true one executes.

Activity diagrams

Visualize a workflow / control flow (like a flowchart) for business processes, use-case flows, or procedural logic. Activities can be sequential or concurrent; an activity is a rounded rectangle.

• Start/end nodes — solid circle (start), filled circle in a circle (final), circle with X (flow final = end of one flow, not all).
• Actions / control flow — rounded rectangles connected by a solid line with an open arrowhead.
• Decision/merge — diamond; decision branches on a guarded condition, merge recombines alternate flows.
• Fork/join — bar; fork splits one flow into concurrent flows, join recombines them (together = synchronization).

Citations

• Software Architect’s Handbook (Packt, 2018), Ch.12 “Creating architecture descriptions (ADs)”, pp. 914-956.