WIP: SDC Decomposition

common-content/en/module/decomposition/adding-like-dislike/index.md

@@ -0,0 +1,64 @@
++++
+title = "Adding like/dislike"
+headless = true
+time = 120
+facilitation = false
+emoji= "👍👎"
+objectives = [
+    "Identify what data needs to be stored and exchanged between a client and server.",
+    "Devise a scheme for differentiating messages with different meanings (e.g. a new message vs a new like).",
+    "Contrast giving updated values as absolute values or relative changes.",
+    "Implement an end-to-end feature involving data updates and reconciliation across a client and server.",
+]
++++
+
+The last requirement we have for our chat application is the ability to like/dislike a message (and see what messages have been liked/disliked).
+
+{{<note type="Exercise">}}
+Think about what information a client would need to provide to a server in order to like/dislike a message.
+
+Think about what information a server would need to provide to a client in order to display how many likes/dislikes a message has.
+
+Think about what information a server would need to provide to a client in order to _update_ how many likes/dislikes a message has.
+
+Write these things down.
+{{</note>}}
+
+### Identifiers
+
+One of the key new requirements to add liking/disliking a message is knowing _which_ message is being liked/disliked.
+
+When a client wants to like a message, it needs some way of saying _this_ is the message I want to like.
+
+This suggests we need a unique identifier for each message:
+* When the server tells a client about a message, it needs to tell it what the identifier is for that message.
+* When a client tells the server it wants to like a message, it needs to tell it the identifier for the message it wants to like.
+* When the server tells a client a message has been liked, it needs to tell the client which message was liked, and the client needs to know enough about that message to be able to update the UI.
+
+### Message formats
+
+Now that your server will be sending multiple kinds of updates ("Here's a new message", or "Here's an update to the number of likes of an existing message"), you'll need to make sure the client knows the difference between these messages. The client will need to know how to act when it receives each kind of message.
+
+### Changes or absolutes?
+
+When new likes happen, a choice we need to make is whether the server should tell a client "this message was liked again" or should tell the client "this message now has 10 likes". Both of these can work.
+
+{{<note type="Exercise">}}
+Write down some advantages and disadvantages of a server -> client update being "+1 compared to before" or "now =10".
+
+Choose which approach you want to take.
+{{</note>}}
+
+{{<note type="Exercise">}}
+Implement liking and disliking messages.
+
+If a message has a non-zero number of likes or dislikes, the frontend needs to show this.
+
+The frontend needs to expose some way for a user to like or dislike any message.
+
+When a user likes or dislikes a message, the frontend needs to tell the backend about this, and the backend needs to notify all clients of this.
+
+When a frontend is notified by a backend about a new like or dislike, it needs to update the UI to show this.
+
+You may do this in your polling implementation, WebSockets implementation, or both.
+{{</note>}}

common-content/en/module/decomposition/adding-quotes/index.md

@@ -0,0 +1,35 @@
++++
+title = "Adding quotes"
+headless = true
+time = 60
+facilitation = false
+emoji= "➕"
+hide_from_overview = true
+objectives = [
+    "POST data from a frontend to a backend in JSON format.",
+]
++++
+
+{{<note type="Exercise">}}
+Add a form to your frontend which allows users to add quotes to the backend's list of quotes.
+
+Note: Your backend expects the quotes to be submitted as JSON. This means you will need to use a `fetch` request from JavaScript to do the POSTing.
+
+You can't just use a `<form method="POST">` tag because that would post the information in a different format. (It would also redirect the user to a page which just says "ok" after submitting the quote, which isn't a great user experience!)
+{{</note>}}
+
+After a user tries to add a quote, if they successfully added the quote we should give the user some feedback so they know it was successful.
+
+If a user tried to add a quote and the `fetch` failed (perhaps because the backend wasn't running), or the response said there was an error, we should give the user some feedback so they know something went wrong (and maybe what they should do about it).
+
+Now that our backend allows users to post quotes, we may want to restrict what can be posted.
+
+For instance, we probably don't want to let people post quotes which are empty.
+
+We may want to do some validation of the input our users give us.
+
+{{<note type="Think">}}
+Where do you think we want to do this validation?
+
+On the frontend? On the backend? Or both?
+{{</note>}}

common-content/en/module/decomposition/backend-limitations/index.md

@@ -0,0 +1,57 @@
++++
+title = "Limitations of backends"
+headless = true
+time = 20
+facilitation = false
+emoji= "📖"
+objectives = [
+    "Explain why a backend on its own doesn't provide reliable data persistence.",
+    "Explain why we may prefer doing work in a frontend rather than backend to avoid latency.",
+]
++++
+
+We've already explored limitations of frontends.
+
+We know a backend is just a program that runs for a long time.
+
+### Lifetime
+
+A major limitation of backends is that "a long time" probably isn't forever.
+
+Sometimes we change the code of the backend. Or need restart the computer it's running on for an upgrade. Or its computer loses power and we need to start it again.
+
+When this happens, the program starts again.
+
+Think back to our quote server that allows users to POST new quotes.
+
+If we had to stop the server and start it again, we would lose all of the quotes users had saved.
+
+They're just stored in a variable, and a variable only lasts while the program it's in is running.
+
+### Location
+
+Another major limitation of a backend is where the code runs.
+
+A backend's code runs on whatever server it's running on.
+
+In contrast, a web frontend's code runs in the user's web browser.
+
+#### Latency
+
+One problem here is latency. Depending on where the backend and the user are physically located, it may take anywhere between 1ms and 500ms for a request to go between them.
+
+If every time you clicked on something on a web page you needed to talk to the backend, you may need to wait half a second just for the request to travel to the server and for the response to travel back, ignoring how long it takes to actually process the request. This would be unusably slow for many applications.
+
+#### Context
+
+Because web frontends run in the user's web browser, they have easy access to lots of information about the user's computer. For instance, they know what language it's configured in, what time zone it's configured in, how big the browser window is, etc.
+
+If our frontend code were instead running in a backend, the browser may need to include all of this information in every request it makes, just in case the backend needs to know it. This has a couple of drawbacks: It makes the requests bigger (which makes them slower, and maybe cost more), and it ends up sharing lots of data with the server that it may not need, which may compromise the user's privacy.
+
+### Pull not push
+
+A backend lives at a well-known address - we know how to connect to it. A user's web browser does not.
+
+This means that a backend cannot try to open a connection to a user's web browser. The web browser needs to initiate the request, and then the backend can reply to the request.
+
+Once a web browser opens a request to a backend, there are some ways to keep a bi-directional communication channel open. But the very first request needs to come from the web browser.

common-content/en/module/decomposition/backend-statefulness/index.md

@@ -0,0 +1,89 @@
++++
+title = "Backend statefulness"
+headless = true
+time = 30
+facilitation = false
+emoji= "📖"
+objectives = [
+    "Identify whether some program is stateful or stateless.",
+]
++++
+
+Our example backend is **stateless**. If you make several requests to it, it will always do the same thing (even though doesn't always return exactly the same result!).
+
+If you made a request from a different computer, or from different country, or on a different day, it would keep doing exactly the same thing. If you restarted the server, it would keep doing exactly the same thing.
+
+If our backend allowed users to add new quotes, it would start having _state_. It would need to remember what quotes had been added. It would be **stateful**.
+
+```js
+import express from "express";
+
+const app = express();
+const port = 3000;
+
+const quotes = [
+  {
+    quote: "Either write something worth reading or do something worth writing.",
+    author: "Benjamin Franklin",
+  },
+  {
+    quote: "I should have been more kind.",
+    author: "Clive James",
+  },
+];
+
+function randomQuote() {
+  const index = Math.floor(Math.random() * quotes.length);
+  return quotes[index];
+}
+
+app.get("/", (req, res) => {
+  const quote = randomQuote();
+  res.send(`"${quote.quote}" -${quote.author}`);
+});
+
+app.post("/", (req, res) => {
+  const bodyBytes = [];
+  req.on("data", chunk => bodyBytes.push(...chunk));
+  req.on("end", () => {
+    const bodyString = String.fromCharCode(...bodyBytes);
+    let body;
+    try {
+      body = JSON.parse(bodyString);
+    } catch (error) {
+      console.error(`Failed to parse body ${bodyString} as JSON: ${error}`);
+      res.status(400).send("Expected body to be JSON.");
+      return;
+    }
+    if (typeof body != "object" || !("quote" in body) || !("author" in body)) {
+      console.error(`Failed to extract quote and author from post body: ${bodyString}`);
+      res.status(400).send("Expected body to be a JSON object containing keys quote and author.");
+      return;
+    }
+    quotes.push({
+      quote: body.quote,
+      author: body.author,
+    });
+    res.send("ok");
+  });
+});
+
+app.listen(port, () => {
+  console.error(`Quote server listening on port ${port}`);
+});
+```
+
+Here we have added a new request handler. If someone makes a POST request to the path `/`, we try to interpret the body they posted as a JSON object.
+
+If we can find a quote and author in it, we will store it in our list of quotes, and start serving it up to future requests.
+
+If we can't process the request, we return an error describing what went wrong.
+
+The details of exactly how we understand the request aren't important. The important thing is that we _are_ taking information from the request, and are then modifying the `quotes` array.
+
+> [!NOTE]
+> **State** is a general term that is used for related but different things in different contexts.
+>
+> State almost always refers to information that we store, which may change.
+
+Because we're _modifying_ the `quotes` array, it is now state.

common-content/en/module/decomposition/chat-application-requirements/index.md

@@ -0,0 +1,40 @@
++++
+title = "Chat application requirements"
+headless = true
+time = 30
+facilitation = false
+emoji= "📝"
+objectives = [
+    "Explain the requirements of our chat application.",
+    "Explain what requirements are out of scope for our chat application.",
+]
++++
+
+We are going to make a chat application which lets multiple users exchange messages.
+
+Let's think about the core requirements for our application:
+* As a user, I can send add a message to the chat.
+* As a user, when I open the chat I see the messages that have been sent by any user.
+* As a user, when someone sends a message, it gets added to what I see.
+* As a user, I can "like" or "dislike" someone's message.
+* When messages are liked or disliked, a count of the likes and dislikes is displayed next to the message.
+
+We can imagine other requirements too (e.g. replying to specific messages, reacting with emojis, being able to edit or delete messages, registering exclusive use of a username, ...). We will stick just to the requirements we've listed.
+
+Because users want to see things, we know we'll need a frontend.
+
+Because multiple users want to be able to share information (messages), we know we'll need a backend for them to communicate via.
+
+### What we already know and what's new
+
+Some of these requirements are similar to the quote server we've already implemented:
+* Adding messages is like adding quotes.
+* Seeing messages is like seeing quotes.
+
+Others are new:
+* Live updates
+* Interacting with a message
+
+First let's make a backend and a frontend to do what we already know. This shouldn't take us very long (we know how to do it, and have done it recently). It will give us a useful framework to experiment with the things that are new to us.
+
+If we thought it would take us a long time to do what we already know, we may approach this differently. We would probably try to work out the new things first. Because they may change how we want to do everything. But because it should be quick to do what we do know, we'll start there.

common-content/en/module/decomposition/data-validation/index.md

@@ -0,0 +1,27 @@
++++
+title = "Data validation"
+headless = true
+time = 60
+facilitation = false
+emoji= "🔎"
+hidden_from_overview = true
+objectives = [
+    "Explain the trade-offs of doing validation on the frontend or backend.",
+]
++++
+
+If we only do the validation on the backend, the user won't know anything is wrong until they submit the form.
+
+If we only do validation on the frontend, it would be possible for users to add invalid quotes by using `curl` themselves, or building their own frontend.
+
+So we normally do validation _twice_ - once in the frontend to give fast feedback (e.g. by adding the `required` attribute to an `<input>` tag), and once in the backend (to make sure no one can sneak bad data to us).
+
+{{<note type="Exercise">}}
+Add validation that authors and quotes are both non-empty, to both your frontend, and your backend.
+
+Make sure when someone tries to post an empty quote, make sure they quickly know what's wrong.
+
+Make sure if someone tries to use `curl` to post an empty quote, it doesn't get saved either.
+
+If the backend rejects a request from the frontend, we should show the user why.
+{{</note>}}

common-content/en/module/decomposition/deploy-chat-application/index.md

@@ -1,11 +1,14 @@
 +++
 title = "Deploying the chat application"
 headless = true
-time = 30
+time = 60
 facilitation = false
-emoji= "📖"
-[objectives]
-    1="Deploy all components of a frontend/backend/database application so it can be used on the internet"
+emoji= "➡️"
+objectives = [
+    "Deploy a frontend and backend so it can be used on the internet.",
+]
 +++
 
-### Deploying the chat application
+{{<note type="Exercise">}}
+Deploy your chat application so that both the frontend and backend are on the Internet, can talk to each other, and can be used by people.
+{{</note>}}

common-content/en/module/decomposition/deploy-trivial-frontend-and-backend/index.md

@@ -0,0 +1,39 @@
++++
+title = "Deploy a frontend and backend"
+headless = true
+time = 60
+facilitation = false
+emoji= "📖"
+objectives = [
+  "Deploy a frontend and backend",
+  "Configure a frontend to talk to a specific deployed backend",
+]
++++
+
+Websites tend to only be useful if they're running somewhere that people can access them.
+
+We need to deploy our frontend and our backend on the internet so that people can use them.
+
+And they need to know how to talk to each other. In your frontend you probably hard-coded your `fetch` to fetch from `http://127.0.0.1:3000`.
+
+First let's deploy our backend somewhere. Then when we know its address, we can update our frontend to talk to our deployed backend, and then deploy it too.
+
+{{<note type="Exercise">}}
+We also need to store our frontend and backend somewhere to deploy them from:
+1. Make a new Git repository on GitHub.
+2. Make a directory called `frontend` in the repository, and move your frontend files there.
+3. Make a directory called `backend` in the repository, and move your backend files there.
+4. Commit your files, and push them to your GitHub repository.
+{{</note>}}
+
+{{<note type="Exercise">}}
+Follow [the Deploying to fly.io guide](/guides/deploying/flyio/setup/) to deploy your backend.
+{{</note>}}
+
+{{<note type="Exercise">}}
+Update your frontend to talk to your deployed backend when it uses `fetch`.
+
+Follow [the Deploying to Netlify guide](/guides/deploying/netlify/) to deploy your frontend.
+{{</note>}}
+
+Make sure you can use your frontend which was deployed to Netlify. Try adding a quote, and make sure it shows up in your frontend.