Coffee | Coding | Computers | Church | What does it all mean?
“Not all design is architectural” is widely repeated. Non-circular answers to “which design is architectural?” are less common. Here's one:
A design or decision is architectural if it impacts the system as a Whole, not merely in part.
(from @visarch 2004, http://www.bredemeyer.com/pdf_files/WhitePapers/ArchitectureAsBusinessCompetency.PDF )
This example is from 2002, by IBM and RDA Corp, published at https://www.ibm.com/developerworks/rational/library/content/03July/2000/2000/2000_RDAEStoreAbbrevSAD.doc.
I'm happy with this style of S.A.D, but there some things I would change if I was in an organisation that produced this kind of document. Broadly, I would related the views back to the structure of the 4+1 approach, rather than simply listing 6 apparently unrelated views.
“
The architecture of a software system requires six distinct views, each view focusing on different aspects of the system. Its purpose is to communicate the major components of the system, how it is structured, the system process flows, and major interfaces. From a high level, the goal is to examine the system from several different perspectives, each providing a different “view” in order to capture all critical system features. A brief description of the six architecture views is provided as follows:
Deployment View – This view documents the physical topology of the system modeled in the Deployment Model. It includes each computer in the implementation and describes how they are interconnected. The configuration for each node is also specified – Operating system, databases, Commercial off-the shelf (COTS), and custom applications.
Logical View – The logical view documents the Design Model, which defines the layers of the application and the primary classes within each layer. The system architect identifies patterns of functionality and creates common mechanisms to provide this functionality to several areas across the application.
Data View – Classes in the logical view are classified as transient or persistent. The persistent classes are mapped to structures on disk, usually into a combination of rows in a relational database. An entity-relationship data model describes the database schema. This view also communicates how the Object-Oriented classes are mapped to the relational tables.
Process (Concurrency) View – This view focuses on the concurrency aspects of the system and how they contend for shared resources (i.e., transaction semantics, etc.). The process view documents the independent threads of execution within the system and describes how they communicate. It also lists the resources in contention by these threads and the transaction model for maintaining integrity with these resources.
Implementation View – This view maps the classes in the Logical View to physical source files and combines the files into deployable components. The implementation view also tracks the dependencies among the components.
Security View – This view focuses on how the system identifies end users, grants authorization to them based on their identity, ensuring integrity of the system and of the data and properly tracking and auditing of system activity.
Note: This is a brief overview of the architecture. The complete eStore SAD is included in the download.
The configuration view presents the topology and its physical and logical connections.
The logical view presents the core design of the system. It presents the primary classes that collaborate to implement the system functionality. It contains the following subsections:
The application is structured along three distinct layers – UI Layer, Business Layer and Data Layer.
UI Layer: Responsible for authentication, presentation
and managing session state.
Business Layer: Exports the business objects defined in the Solution Model class analysis. Maintains no knowledge of presentation. Insulates the UI Layer from database design. Responsible for complex business rule logic.
Data Layer: Responsible for managing persistent data and transactions. Maps business objects to physical relational tables. Responsible for data integrity, transactions and data intensive business rules such as unique name on a column.
The following diagram illustrates the classes and their relationships exported from the business layer to the presentation layer.
Figure 1: UI Session Stack Class Diagram
Pet Store’s business layer is implemented by leveraging the services provided by IT FlightPlan’s Software Library. The business classes exported by the business layer are either BusinessClasses or ReferenceClasses. IT FlightPlan’s Software Library exports a BusinessClass base, abstract class and an IReferenceClass interface. The following diagram shows how the classes in the business layer are implemented – the session BusinessClasses inherit from BusinessClass while the cached classes implement the IReferenceClass interface.
The Database Model is presented as a logical view, physical view and data dictionary. The logical data model is included in this overview.
The Process View focuses on the parallel processing aspects within the system. eStore deals with concurrency in two distinct areas -
2. Transaction design for shared resources,
A. Records in the PetStore database – single data source
B. Updates to PetStore database and the Credit Authorizer
C. Shared objects in memory
This diagram shows the major threads and context switches involved with processing a web request. IIS allocates a pool of worker threads to process HTTP requests and posts.
All transactions are encapsulated within a call from the BusinessLayer to a stored procedure. Any SQL errors within a stored procedure force a rollback and the error is raised to the BusinessLayer.
Account data integrity is maintained through optimistic concurrency. A unique version timestamp is returned with each head Account object.
There is one point in the application where there are two distinct data sources, so this leads to a critical region in the code. ConfirmAddresses invokes CreditAuthorizer to charge the customer’s credit card. If successful, it returns a credit authorization code, which is stored in the Payment when the Order is saved. We have an exposure in the case where the charge is successful, but Order.save() fails. CreditAuthorizer does not support two-phased commit transactions, so RDA Pet Store will continue to reconcile its daily charges with the Credit Authorizer at the close of each business day.
The static reference objects that are shared across all sessions have only one instance per web server. All sessions refer to this single instance. Since these classes are loaded when the application starts and are not modified, semaphores are not required for synchronization.
The implementation view describes how the software is physically contained in files and how files combine to form components. At the highest level, the application is comprised of packages.
The 3 layers outlined in the Logical View (UI, Business and Data) are implemented with the above packages as follows –
UI Layer:
· ITFlightPlanSWLib - generic UI utilities to bind/unbind attributes to UI controls
Business Layer:
· ITFlightPlanSWLib packages – reusable mechanisms the provide persistence and error handling\
Data Layer:
· DataLayer – the Pet Store tables, stored procedures and reference data
· ITFlightPlanSWLib – Generic wrapper interface to access ADO
The security view describes how the system implements the security requirements specified in the Detailed Spec. Security design is presented in the following sub-areas.
ü User Identification & Authentication – How does the system identify users and verify it is them?
ü Authorization – Once authenticated, who is allowed to do what?
ü Data Integrity and Privacy – Ensure the integrity of the data is not compromised.
ü Non-repudiation and Auditing – Ensure the end user cannot cover up their tracks. Record access to the data so we know who’s done what.
eStore uses a single stored procedure – getAccountForUserID – to fetch the account information for a particular user and stores it in the session stack.
Since the authenticated user contained in the session stack, eStore relies on the integrity of .Net sessions to ensure that users can only access their own accounts.
V1.0 of RDA Pet Store provides minimal protection of data. Passwords are encrypted before they are stored in the database.
Extending Pet Store to be more secure, we would use SSL to transmit password and credit card information.
Each table in the database provides last modified by and last modified timestamp columns. The authenticated userID parameter on the save stored procedure is set in these columns on all inserts and updates.
Let me show you how I document smallish software systems with, typically, no more than four UML diagrams. We'll cover the questions, what is worth diagramming? and what can I do with these diagrams anyway? and we'll cover enough UML to be useful.
I will use the example of developing a “lead generation” website, which should be simple enough to not get bogged down, but complex enough to answer some of the but how do I …? questions that more complex systems raise.
Use diagrams as starting point to discuss, describe and explain your system. A diagram can give an instant overview of some aspect of the system. It can show important relationships on a single sheet of paper. It can raise important questions and show design decisions.
The UML is a visual modelling language. It has a vocabulary and grammar for diagramming software such that the diagram is a precise statement. So it can be used to show and explain software architecture.
The UML is the only diagramming standard left standing (with, perhaps, one exception that we'll see later). You may be tempted to compete in this uncrowded field of standards for software diagrams. I comment only that the UML contains several decades of work by several thoughtful people and if you can produce a usable standard that is simpler, quicker to learn, and not unhelpfully imprecise, then I shall be impressed.
You may also be tempted — as many, many of your colleagues have been — to just do without a standard. I hope these few examples will persuade you that learning a standard is less work than you fear and more useful than you expect.
The UML tells you how to diagram once you've decided what to diagram. “2+1” is a minimal decision about what to diagram. It suggests a couple of diagrams for the logical view of your software and one for the physical view (we'll explain what those words mean, too). That's the 2. But it starts with the 1, which is the context.
Always start with context. Always start with simple.
The context diagram should make sense to your non-technical customer and can be so simple you wouldn't even give it a second glance. It shows:
In the UML, anyone or anything who uses the system, or is relied on by the system to do its thing, is an Actor. What the system will do is a UseCase. A UseCase is a instance of the system being used to do something. It is shown on a diagram just by its name, which is a single descriptive phrase, in an ellipse.
Use the diagram to discuss scope, expectations and dependencies with the system's customers and with the development team who will build it. Its simplicity and brevity should also clarify what is not (or not yet) expected of the system. Like user stories, the brevity calls for conversation to clarify. Complex Use Cases call for detailed careful business analysis too, but that is done with words, not pictures.
For your developers, this diagram is the high level overview of what they're delivering — everything inside the box — and what the system will need for it to work — everything outside the box.
I really like having a “hand drawn” look when first showing diagrams, because it says “work in progress” and invites participation. A precisely drawn diagram risks the impression of being a final decision.
I try to draw diagrams to be read from top left to bottom right. So I put “active” Actors—the users—on the left, and “dependency” actors on the right. That's not a part of UML, but it's part of how I will talk through the diagram.
Here's the same diagram later on on the project. In phase two, we're giving visitors SMS feedback, and adding a whole new bit of functionality to read events from the customer service team and integrate then with web analytics.
What if you have lots of use cases? Don't put more on one diagram than you can usefully discuss in a single session. Pick out the main use cases & those that show the main external dependencies (which probably means, the ones that pose the highest risk to your project). Optionally, have a second diagram for all use cases, but only if you have an audience for it.
There are 3 things you need to know for this diagram:
Actor, UseCase, and Subject aka System Boundary
Here are their definitions, which I've abbreviated from the UML 2.5 spec, section 18 Use Cases.
UseCases are a means to capture the requirements of systems, i.e., what systems are supposed to do. The key concepts specified in this clause are Actors, UseCases, and subjects. Each UseCase’s subject represents a system under consideration to which the UseCase applies. Users and any other systems that may interact with a subject are represented as Actors.
A UseCase is a specification of behavior. An instance of a UseCase refers to an occurrence of the emergent behavior that conforms to the corresponding UseCase. Such instances are often described by Interactions.
An Actor models a type of role played by an entity that interacts with the subjects of its associated UseCases (e.g., by exchanging signals and data). Actors may represent roles played by human users, external hardware, or other systems.
NOTE. An Actor does not necessarily represent a specific physical entity but instead a particular role of some entity that is relevant to the specification of its associated UseCases. Thus, a single physical instance may play the role of several different Actors and, conversely, a given Actor may be played by multiple different instances.
NOTE. The term “role” is used informally here and does not imply any technical definition of that term found elsewhere in this specification.
A UseCase is shown as an ellipse, either containing the name of the UseCase or with the name of the UseCase placed below the ellipse. An optional stereotype keyword may be placed above the name.
A subject for a set of UseCases (sometimes called a system boundary) may be shown as a rectangle with its name in the top-left corner, with the UseCase ellipses visually located inside this rectangle.
An Actor is represented by a “stick man” icon with the name of the Actor in the vicinity (usually above or below) the icon. An Actor may also be shown as a Classifier rectangle with the keyword «actor»
Other icons that convey the kind of Actor may also be used to denote an Actor, such as using a separate icon for non- human Actors.
The spec: https://www.omg.org/spec/UML
I have used 3 more UML features to add explanations:
Bob Martin raises a good example in InformIT: Robert C. Martin’s Clean Code Tip of the Week #1: An Accidental Doppelgänger in Ruby > Duplication of two functions that do the same thing but mean different things by it.
I recently stumbled into a slightly different take on the question of should a function say what it does or what it intends?
When a function implements business process Alpha that today consists of steps A and B (but tomorrow may change) should you call the function DoBusinessProcessAlpha or call it DoStepsAandB?
One answer would be, if the function is in a public package which exposes business functionality then the name should probably show that it does BusinessProcessAlpha. But if it is a private, not exposed, function then the reader is probably looking for the detail, that it does StepsAandB.
The question is more awkward if Steps A and B are themselves business process functions. That is, if you asked your customer, they would understand what steps A and B mean.
I suppose in that case you could always call it DoAlphaAsStepsAandB().