Homework 4: Architecture

Due Nov 2, 2020 by 3:30pm
Points 5
Submitting a website url

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 are 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 software 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).

To simplify this, we're going to use the architectural concepts relevant to the Model-View-Controller and Client-Server architectures ubiquitous on the web:

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 homework is to decide how you're going to organize your clients, servers, models, views, and controllers. To do this, you're going to create two things.

A description of all components

First, write a Markdown file in your GitHub repository 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.

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 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 with 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 specifies the requests that the component can receive from other components. For example, the LearningModel model above should have functions defined for the three functions the GameController can call on the MasteryModel.

Commit all of your stubs to your GitHub repository.

Approach

To generate the two description and stubs, address any feedback you received on your requirements, and then follow the Architecture Design Links to an external site. strategy on HowToo. Leave a comment on your experience using the strategy for 1 point of credit. Remember that the comment must not be anonymous.

As with past homeworks, create a milestone in GitHub, and create issues for your tasks. Your project manager's job is to successfully move you through this process.

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.

In class

In Discord > Team Channels

Developers lead

Your goal for class is to complete as much of the architecture as you can in class, using the strategy above.

Grading Criteria

In addition to 1 point for a non-anonymous comment on HowToo for the strategy, your architectural specification will be 4 points.

Submit a link to Markdown page in your repository that contains your architecture description. We will review it and all of the source files in your repository to determine your grade.

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.1 points. We will read both your document and your code for clarity and consistency.

Rubric

Find a Rubric

Title:

Title

Criteria

Ratings

Pts

Edit criterion description Delete criterion row

Description of criterion

Range

threshold: 5 pts

Edit rating Delete rating

5 pts

Full Marks

Edit rating Delete rating

0 pts

No Marks

pts