TODOOSE

by jhu-oose

GitHub Readme.md

TODOOSE

A to-do application for OOSE

Live Version

Code Base

Video on Getting Started

Videos on Building TODOOSE from Scratch

Build Status

Deploy

Architecture

TODOOSE is a web application. It’s divided in two components, the server, and the client. It uses the tools in the Toolbox.

Server

Server: The entry point of the Server, including the main method that is called when the Server starts. The Server class uses Javalin to start a web server, sets up routing for incoming HTTP requests, connects to the SQLite database, and so forth.

Item: The class containing the logic of the application—something called a model. TODOOSE is an artificially simple application for pedagogical purposes, so this model doesn’t include much logic (it only holds data), and it’s the only model in the application. A more realistic to-do application would probably include the notion of, for example, when items are due, who’s assigned to each item, and so forth, and there would be multiple models responsible for determining who has overdue items, how a project is progressing over time, and so forth. If the application were a game, for example, the models are where the game rules would be.

ItemsRepository: A repository is a bridge between models (see above) and the database: the repository saves Items to the database, finds Items in the database, removes Items from the database, and so forth. Repositories are where you can find SQL in the application. This is the only repository in the application because TODOOSE only has one model, but typical applications include more repositories. Do not confuse the term repository used here with the term repository used by Git—they are completely different things.

ItemsController: A controller handles the HTTP requests as they come in, orchestrate the work of models and repositories (see above), and determine what the HTTP response should be.

Client

The code for the Client runs directly on the user’s browser, and it is sent there by the Server. When the user visits https://todoose.herokuapp.com, for example, the Server knows that by convention the user wants the file index.html, so it sends that file to the user’s browser. This is different from what happens when the browser requests https://todoose.herokuapp.com/items, for example, which is one of the API endpoints (see below) with functionality for TODOOSE. In this case, the Server has to use the router, controllers, models, repositories, and so forth, to produce a JSON response.

index.html: The entry point of the Client, which sets up the stylesheets and the JavaScript (see below).

styles.css: The stylesheets for the application. The styles for the whole application live in one file because they’re very simple, but in a more sophisticated application it may be necessary to break them apart in multiple files, for example, one file per collection of components (see below).

client.js: The entry point for the JavaScript portion of the Client, which mounts the React component.

ItemsComponents.js: A collection of React components for Items.

vendor/: A directory containing the libraries we’re using on the Client: React and Babel (to add support for JSX).

API Documentation

Postman Collection: The Server and the Client communicate through an API. The Postman Collection documents what are the endpoints that the Server must provide and the Client may consume. It includes examples of the API in use as well as tests (see below).

Tests

ItemTests: Automated tests for the Item model (see above). This is something called Unit Tests, because it tests an unit of code (in this case, a model). These tests are artificially simple because the models in TODOOSE are artificially simple. In a more realistic application these tests would exercise the logic in the models, for example, the rules of a game.

Postman Tests: Automated tests for the Server as a whole—they’re sometimes called System Tests. They simulate what a browser would do, communicating with the Server through HTTP. To run these tests, you must start the server and import the Postman Collection.

Auxiliary Files

.gitignore: Configuration for Git, specifying which files must not be versioned (tracked), because they belong not the project, but the developer’s machine, for example, the .DS_Store files generated by Finder in macOS.

.travis.yml: Configuration for Travis CI, specifying how to run the tests for TODOOSE.

app.json: Configuration for the Deploy to Heroku button above.

build.gradle: Configuration for Gradle, which lists the libraries in which TODOOSE depends, specifies that Server (see above) is the class that must run when the Server starts, specifies how to run unit tests (see above), and so forth.

CODE_OF_CONDUCT.md: The Code of Conduct for TODOOSE contributors.

gradlew and gradlew.bat: Wrappers for Gradle for macOS/Linux and Windows, respectively. These wrappers install and run Gradle, simplifying the setup process.

LICENSE: The License for TODOOSE.

Procfile: Configuration for Heroku, specifying how to start the application.

README.md: This documentation.

settings.gradle: Gradle configuration generated by IntelliJ.

system.properties: Configuration for Heroku, specifying which version of Java to run.