Back to Homepage

Homework 4: Architecture Specifications

In Homework 3, you detailed what your software is going to do from a design perspective. All of those choices you made are about the problem you're solving with the software; those details concern the world. In this homework, you're going to specify how you're going to achieve those requirements, defining your software's architecture.

Unlike in building architecture, where there are standards for blueprints, there is no agreed upon way to specify architectures. There are highly formal tools which precisely detail the components and connectors of a system so that code can even be automatically generated from these architectural specifications (Shaw et al. 1995). Some architectural specifications are just vague sketched diagrams on a whiteboard (Cherubini et al. 2007).

One key idea in designing architecture is to imagine you're inventing new "species" of creatures. Unlike living species, however, which are concerned with survival, your components are entities that have responsibilities for storing data and accomplishing computation of some kind. Inventing new species is a creative activity; you want to think about what they will and won't do, give them names, and tell stories about how they interact with each other, exchanging data.

To capture your architecture, write a Markdown file in your GitHub repository that specifies all the components in your system. For each component:

• Include a name
• Give a natural language descriptions of the components responsibilities.
• Enumerate the data and functionality it will encapsulate.
• For each kind of data, specify in natural language the exact data type
• For each kind of functionality, specify in natural language the inputs and outputs and their exact data types and the properties of the intended output

In addition to details about individual components, write a natural language description of how the components interact, describing their connectors. (Are they communicating with events, function calls, timers, or other kinds of mechanisms?). If it helps clarity, create diagrams to specify these interactions.

While I'm using the word “component” above, it is reasonable to think of components as “classes,” if you want to use an object-oriented paradigm to organize your architecture. Within this paradigm, all of the details above would practically constitute API documentation for all of the classes in your implementation. For example, consider Google Map's JavaScript API documentation. It cleanly enumerates a set of classes and objects, the data and functions that each encapsulates, events that can occur that these components react to, along with all of the details about data type and behavior we've required above. (While it's one of the better examples of documentation on the web, it's still not great: it's clearly designed for people who are referencing the architectural details and not trying to learn them.).

While doing this, remember that the document you're writing is not intended to satisfy us. It's intended to help you organize, plan, and streamline your implementation efforts this quarter. Therefore, focus on writing a document that's useful to you. Think of the document like a big to-do list for all of the code you have to write.

Lastly, consider your process for writing your architectural specification. I recommend the following:

1. Address the feedback you received on your requirements, resolving any issues your classmates identified (1 hour).
2. Once you're happy with your requirements, meet as a group and begin generating ideas for components that can satisfy all of your requirements (1 hour).
3. Sketch your ideas on a whiteboard and refine them as you identify open questions about their responsibilities and how components will communicate (1 hour).
4. Once you converge toward a set of components you think you think can meet your requirements, begin outlining your document (1 hour).
5. To identify gaps in your architecture, implement a simple prototype of your application that includes all of the structure of the components but none of the functionality. You may also want to do a feasibility assessment of key functionality (testing APIs you might use, etc.), to verify that the architecture you'll planning will actually work. Refine your architecture accordingly (2 hours).
6. As you write your document and prototype your architecture, other questions will arise. Schedule time with your team to resolve these questions (2 hours).
7. Edit your document for consistency and clarity (1 hour)

A lot of the work above can be delegated to individual teammates. Use your management structure to assign responsibilities to ensure the work gets done on time.

While you're producing a document, the real goal of architecture is to make sure everyone on your team has a consistent, detailed understanding of the architecture. If they don't, you'll end up with a ball of mud. To test this, quiz each other on the architecture you have planned: can each of you explain it in detail? If not, keep explaining it to each other until you have the same understanding in your heads and in your document.

Example

Here is one example of a solid architecture description from a team in a previous year. It provided a detailed enumeration of components, clear explanations of functionality and data, and clearly-explained interactions between components. The document could have been even clearer by using diagrams to show interactions between components, and by providing more detail about the mechanisms that components would use to interact, but it's a good start.

Grading Criteria

Submit a GitHub URL to your architecture document in Canvas.

The most important qualities of an architectural specification are clarity and consistency. If something is ambiguous or inconsistent, your collaboration will be constantly interrupted by the need to clarify and you'll likely write code that you have to discard or change because of your misinterpretations. To incentivize you writing a clear, consistent document, for every unclear or inconsistent detail include, your team will lose 0.1 points. I'll give you three free ambiguities before I start deducting points (all documents have some ambiguities).

Further Reading

Shaw, M., DeLine, R., Klein, D. V., Ross, T. L., Young, D. M., & Zelesnik, G. (1995). Abstractions for software architecture and tools to support them. IEEE Transactions on Software Engineering, 21(4), 314-335.

Cherubini, M., Venolia, G., DeLine, R., & Ko, A. J. (2007, April). Let's go to the whiteboard: how and why software developers use drawings. In Proceedings of the SIGCHI conference on Human factors in computing systems (pp. 557-566).