In Stage 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 are solving with the software; those details concern the world. In this Stage, you’re going to specify how you’re going to achieve those requirements, defining your software’s architecture.
To simplify this, we’re going to use the architectural concepts relevant to the Model-View-Controller and Client-Server architectures:
Your job in this Stage is to decide how you’re going to organize your clients, servers, models, views, and controllers. To do this, your team is going to create two things.
First, write a Word file that specifies all of the models, controllers, and views in your application. For each, describe:
Here’s an example of a description of a model component for our arithmetic game example from previous homeworks:
LearningModel
The architecture of the game would therefore also contain descriptions of the GameController, but also several views components that implement the user interface of the game, such as the view that displays the question, the view that displays the answer, the start screen view, etc.
How many components should you have? There is no right number, but consider a few extremes. If you only had one monolithic component, where there was no encapsulation between any of the data and functionality, you’d have a big “ball of mud” architecture that’s going to be hard to understand, and therefore hard to evolve and repair. If you had a thousand little components for every tiny bit of functionality, most of your code would be communicating between components. You want something in the middle, where there’s enough division of responsibilities that everyone on your team can understand how the functionality is organized, but not so many that you’re writing a lot of extra code just to make things talk to each other.
Note that you don’t have to specify components you aren’t building. For example, if you choose to use something like Firebase, you don’t need to specify Firebase. But some of your components may need to mention that they’re going to communicate with cloud storage to store and retrieve data. Additionally, you’ll likely have a client-side model of data in the cloud storage, so your client side components can access the data.
Once you have all of your components described, create stubs to represent all of these components and their functionality as source files. A stub is a partial implementation of something in source code, intended to help you architect the larger pieces of an implementation without fully implementing them.
For example, here is a stub of a function that takes an age in years and returns an array of strings describing civil rights movements that someone likely experienced in their life:
function getCivilRightsExperiences(age) {
// TODO Replace with actual algorithm
return ["Voting rights act of 1965"];
}
Notice how the stub specifies the inputs and outputs, but nothing about how they’re computed? It’s just a stand-in for functionality you’ll eventually write.
Since you’re using HTML, CSS, JavaScript, and/or React, there are a few clear implications for the kind of stubs you’ll create:
None of these components need to have functionality, but they do have to have names, source files, and all of the function headers, with arguments, return values, preconditions, and postconditions, to specify the requests that the component can receive from other components. For example, the LearningModelmodel above should have functions defined for the three functions the GameController can call on the MasteryModel.
Developers Your goal is to complete as much of the architecture as you can in the discussion.
The most important qualities of an architectural specification are clarity and consistency. If something is unclear 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.2 points. We will read both your document and your code for clarity and consistency.