Tasks

For this stage, you will turn in two things:

1. A mapping from your API design to that for Matrix.
2. A testing plan for the servers.

These are explained in more detail below.

Mapping

It's often the case that you think you need to build something, and then discover that there's already a robust library, package, system, etc. that already implements it. In such cases, it makes no sense to reinvent the wheel: you should just use what is already out there, which has probably gone through several design iterations, testing rounds, etc. This is especially a peril to look out for with coding agents, which seem to have a tendency to generate code from scratch rather than first looking for existing solutions.

This is the situation we are simulating here. We had you design your own server API; but Matrix already implements all this, and more! Your mental model is in terms of your design. Now you have to adapt it to what Matrix offers, so you can get its advantages.

Therefore, your task is to learn enough about Matrix, and then generate a mapping from your API design to that already provided by Matrix. The direction of the mapping is important. Matrix is a large library with many features, many of which you probably did not imagine in your design. You will only focus on those that you did.

To do this effectively, you will need to learn Matrix! This is a task we are explicitly asking you to use Claude to help you with. Good coding models these days have a lot of useful information about systems like Matrix (at least up to the point of their training date…). These are complex systems, so “learning” will be a multi-step process. Each of you will may be at a different point in your computing maturity and experience and may need different levels of explanation. A robust model is good for this, and Claude seems to have pretty good knowledge about Matrix (we've poked at it).

Testing

We are saving you the bother of having to set up and run a Matrix server. If, however, Matrix didn't already exist, you would not only need to get a server up and running, you would also need to test it. If it's not implemented correctly (or at least according to your expectations of it), debugging would be very painful: you'd be sending messages, they may just get dropped, your user interface would simply appear unresponsive, etc. In a way it's much worse than when everything is all in one programming language and program, and tools like the type-checker can help you out.

To simulate this experience for you, we have set up an array of “Matrix” implementations. One of them is correct; the others have a bug. You really want to make sure you're programming against the correct one! Therefore, you need to write a test suite that is good enough to tell the good one apart from the bad. In other classes you have probably seen the terminology of “wheats” (correct) and “chaffs” (incorrect); same idea here.

Of course, when you are yourself implementing the server, it's not much good to just know that it has “a bug”. You need the test suite to also be diagnostic: to tell you what is wrong so that you (and/or your agent) can fix it. Therefore, you should make sure the test suite you develop also provides some information about what the failure is.

For now, as usual, you are just submitting a testing plan. Think through what situations you need to test. For the next stage you will turn the plan into an actual test suite. The need to provide diagnostics makes the planning part especially important: think through situations that need to be represented.

Assignment Tasks

You are NOT writing code for this stage; just write this design document.

Task 1: Write up your matrix mapping (as described above) in a file named MATRIX-MAPPING.md. Push this file to your repo.

Task 2: Write up your testing plan (as described above) in a file named TESTING-PLAN.md. Push this file to your repo.

Task 3: Be sure to keep updating your reflection journal (and submit the URL to us). We're particularly interested in how you find the process of learning enough about Matrix to do this assignment. Please add a note to your journal telling us how much prior experience you had with servers (e.g., this is completely new to me, know a little but never worked with one, have experience setting them up, etc).