Stage 4: 10/10– 10/23 (Sunday), 11:59pm (CST) Architecture and Plan.
Architecture
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:
- Client-Server architectures involve two kinds of components—clients and servers—exchanging messages with each other. On the internet, these messages are http requests.
- Model-View-Controller architectures involve a model to persist and retrieve data, views to display data and elicit it from users, and a controller to implement the application’s logic for passing data back and forth between the model and views, as well as manipulating data.
- In web applications, models, views, and controllers can live on either the client, the server, or both. For example, when you use a database, the model is on the server side. But your application might only store data on the client side if it only needs to persist data on the device accessing the site. It might also persist all data on the server, but then send all of the data on the client, so there are actually models on both the client and the server. The same is true of views: some applications render all HTML/CSS/JavaScript views on the client side, while others render all HTML and CSS on the server.
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.
1. A description of all components
First, write a Word file that specifies all of the models, controllers, and views in your application. For each, describe:
- What the component’s responsibility is
- Whether the component resides on the client, the server, or both
- What other components the component needs to communicate with and precisely what they will communicate.
Here’s an example of a description of a model component for our arithmetic game example from previous homeworks:
LearningModel
- This component is a model that stores all of the questions the game has asked the player and all of the answers the player has given to the game.
- The model resides only on the client.
-
Only the GameController communicates with the model. It communicates the following:
- The GameController can ask the LearningModel to store a question/answer pair
- The GameController can ask the LearningModel for the proportion of correct answers
- The GameController can ask the LearningModel for all of the stored question/answer pairs.
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.
2. Stubs for all components
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:
- All of your views will either be React components or some combination of HTML, CSS, and JavaScript. When you make each component, you’ll have to decide how you’ll be implementing them.
- Your model will either be some form of JavaScript on the client side or any arbitrary combination of server-side scripting language and/or a database.
- Your controller will either be JavaScript, a React component, or a server-side script, depending on where you decide to implement your application logic.
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.
Stage 4 Architecture Submission Instructions:
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.
