Banjo app

Now it's your turn to create a Banjo app -- as a team. Before you start programming, you need to design your app by considering a few key questions.

Teacher portal case study

Start by reading this case study of a much larger design process, for a different kind of software. However, the design questions which need to be answered are the same.

Splitting into components

This project is done in a team, and your app must be built out of at least two components, split across sub-teams. Two common ways to split a project like this:

• Front-end and back-end. One sub-team builds a Banjo server (models and views, like riddle_server), and another builds a client that talks to it (like client.py in the Riddles lab) -- a Terminal app, a script, or another Banjo app that calls the first one's routes.
• Modular decomposition. One app, but broken into two or more pieces with a clear boundary -- for example, a layer that handles fetching/importing data (like scrape-schema-recipe in the Cookbook example below) separated from the layer that serves it, or two clearly separated concerns within the same app (e.g., one sub-team owns everything about users, another owns everything about the app's core content).

Whichever way you split it, each sub-team answers the design questions below for their own component. But the most important part happens before anyone writes code: the whole team has to agree on the contract for the interface between components -- exactly which routes exist, what arguments each one takes, and what it returns. (This is exactly the kind of contract RiddleAPI and riddle_server share in the Riddles and Server labs -- neither side needs to know how the other is implemented, only what to expect from it.) Write this contract down in planning.md before implementation starts. If a sub-team changes the contract later, they need to tell the other sub-team -- that's the whole point of writing it down.

Example: Cookbook

💻 Now let's look at the design of an app you could create in Banjo. The Cookbook example below answers the design questions for a single component, built by one person -- your team will answer the same four questions once per component, and then add the interface contract on top. Run the server by moving into the cookbook directory, running banjo, and opening http://localhost:8000/api. Try out the app: you can import recipes by URL from cooking sites like All Recipes, you can search for recipes, and you can add notes.

1. Who will use your app? (Who is your app's target user?) This is an app for people who like to cook, specifically me. I expect users to host this app on their own computer for their own use. The app will not support multiple users.

2. What need or problem will your app solve? How do you know this is really a need for your target user? How does the target user currently deal with the problem?

I have three main goals for this app:

1. Collect recipes I like.
2. Search for a recipe when I'm thinking about what to cook.
3. Store notes about the recipe.

Honestly, I'm creating this app for myself, so I'm not worried about whether it meets other people's needs. The main alternative to this app is searching for recipes online, but I find online recipe websites unpleasant to use because they have so many ads and unnecessary text.

3. How will your app's design meet the need you have identified?

• To collect recipes, I will import them from recipe websites. I found a Python project called scrape-schema-recipe which reads metadata from recipes, so the hard work is done! (You can install new packages in your project using poetry add project-name.)
• I will support search for recipes by name or by ingredient.
• I will also support attaching notes to a recipe.

4. How could your app possibly cause harm? (For example, could someone get hurt if data leaked or if someone used the app inappropriately?) What steps will you take to ensure that nobody is harmed by your app?

This app is unlikely to cause harm. Because the app is only intended for an individual user on their own computer, we don't have to worry about abuse from other users. There is no issue with violating the copyright of recipe websites--importing recipes is equivalent to saving a webpage. It is possible that recipes have been uploaded to recipe websites in violation of copyright.

Assignment

Now implement your design as a Banjo app -- each sub-team building their own component against the contract you agreed on.

💻 To get started, create a new directory for your project (the code below uses project, but you might want to choose a more descriptive name), create an app directory inside, and create models.py and views.py inside of app:

$ mkdir project
$ cd project
$ mkdir app
$ touch app/models.py
$ touch app/views.py

Open your project in your editor:

$ code .

And then start the Banjo server. We use --debug so that we'll get useful error messages when something goes wrong.

$ banjo --debug

Open your project in your browser at http://localhost:8000. Banjo will live-reload your app, so as you make changes to models.py or views.py, the web page connects to the latest version of your code.

Develop your app step-by-step, making small changes and testing them out. It usually works better to work bottom-up for web apps, starting by creating your models and then creating your views, but it's up to you.

Wrapping up