Check In

Check in is an online web platform for administering surveys for CS labs and analysing the responses, with the goal of flagging students at risk and assisting instructors with interventions.

Demo Application

An evaluation version of the application is hosted at https://qlitmnms3a-vioxgpwe4okw6.eu.s5y.io/ . It will be available until November 30th, then it will be taken down.

Login using the credentials below for the test instructor and user.

• Student: [email protected] Pass: password
• Instructor: [email protected] Pass: password

Requirements

This project is developed using the Symfony framework. It is recommended that you follow their setup instructions and install their CLI tool.

The main dependencies for backend development are:

• Make: For running the developer build scripts.
• PHP 7.4 or above
• Composer: For managing PHP dependencies.
• Symfony CLI: For serving the Symfony application.
• Docker / Docker Compose: For containerising the DB.
• Cron / Crontab: For running the application cron tasks.

The main dependencies for frontend development are:

• Node JS 14.2.0 or above
• Yarn

In addition, this project uses Symfony Encore, which is a webpack variant specifically for Symfony. This is installed via the Composer / Yarn package managers, as are other dependencies.

Installation

All of the below commands should be run from the root of the check-in folder, as all commands use relative paths.

1. Run make dev for an interactive guide to setting up the development environment. This will prompt you to open terminal windows and run additional commands. Also it will ask you for decisions regarding the following:
   1. Running make backend/cron_setup to add a cron task that symfony uses for running the src/Task/FlagStudentsTask.php task. This may require administrator privileges / chmod-ing the file for execution. It can be omitted, but student flagging will not function as intended.
   2. Creating application fixtures (fake data). There are two variants:
   • make fixtures/test: This creates fixed data which was used for manual acceptance tests (see Testing section). The corresponding fixture class is src/DataFixtures/TestFixtures.php.
   • make fixtures/evaluation: This creates randomised data representative of a computer science programme at a university. The corresponding fixture class is src/DataFixtures/EvaluationFixtures.php.

Note: Though the evaluation fixtures have been optimised as much as possible, it generates considerable data (300 students). You might want to grab a coffee while it generates!

Usage

• Navigate to the local web server in your browser (see Installation). You can check the port that the Local Web Server is using using make backend/status.
• Login using the credentials below for the test instructor and user.
  • Student: [email protected] Pass: password
  • Instructor: [email protected] Pass: password
• The evaluation fixtures also produce .csv files in the root directory with all generated user emails. You can use any email from these with the password password to login.
• You can stop the server by running make backend/stop.
• See docs/UserGuide.pdf for a comprehensive user guide.

Code

All code has been written to be as self documenting as possible. However, comments are included where necessary and to describe key methods

The directory is structured according to Symfony best practices, with additional files and folders specific to this project. The structure is provided below with annotations for important or customised additions.

Directory Structure and Key Items

📦.github

┗ 📂workflows

┃ ┗ 📜php.yml

^{This contains a continuous integration script which automates builds and tests when creating a pull request on the GitHub repository.}

📦.symfony

^{This contains configuration used for hosting the evaluation application on Symfony Cloud.}

📦assets

^{This contains the frontend source code.}

┣ 📂css

^{This contains the SASS CSS files for additional frontend styling.}

┗ 📂js

┃ ┣ 📂lib

^{This contains javascript libraries and custom code used by the project.}

┃ ┣ 📂vue

^{This contains custom Vue.js components for building the XY grid interface.}

┃ ┣ 📜app.js

^{This is the first of Webpack's entry points. All javascript to be inserted at the bottom of each page's <body> tag is imported here.}

┃ ┗ 📜preload.js

^{This is the second of Webpack's entry points. All javascript to be inserted at the <head> of each page is imported here.}

📦bin

^{This contains shell and php scripts}

**┣ ...

┣ 📜dev.sh**

^{This script guides the user through the setup process for development.}

┗ 📜setup_cron.sh

^{This script sets up a crontab entry for the application.}

📦config

^{Configuration files for symfony and its bundles}

┣ 📂packages

^{Contains Symfony bundle configurations for different environments}

┃ ┣ ...

┃ ┣ 📜twig.yaml

^{Contains Twig globals and points the application to [custom form object templates](https://symfony.com/doc/current/form/form_themes.html#creating-your- own-form-theme)}

┣ 📂routes

^{Route configuration is here. It is set up to use annotations on controller methods.}

┣ 📂secrets

┃ ┗ 📂dev

^{Contains encrypted sentiment analysis API credentials so [other developers can use the api] (https://symfony.com/doc/current/configuration/secrets.html). The private key is NOT included in this repository.}

┣ 📜bundles.php

^{This lists and imports all external Symfony bundles used in this application.}

┣ 📜routes.yaml

^{Adds global routing. Namely redirecting '/' to '/courses'.}

┗ 📜services.yaml

^{Sets up Symfony's service container which is used for dependency injection.}

📦docs

^{Contains all project documentation.}

┗ 📂testing

┃ ┣ 📂coverage

┃ ┃ ┗ 📜index.html

^{This is entry point for the HTML test coverage report.}

┃ ┗ 📜ManualAcceptanceTests.pdf

^{This is the manual acceptance testing report.}

┗ 📂evaluation

^{Contains evaluation fixture user accounts in .csv form}

📦public

┗ 📜index.php

^{Entry point for the application.}

📦src

^{The backend source code}

┣ 📂Containers

┃ ┣ 📂Risk

^{Classes for wrapping entities associated with risk calculation and providing helper methods for calculating risk, rendering, etc.}

┣ 📂Controller

^{Classes for page routing and logic.}

┣ 📂DataFixtures

^{Classes for generating mock data.}

┣ 📂Entity

^{ORM classes}

┣ 📂Form

┃ ┗ 📂Type

^{Custom form classes to bind forms to entities}

┣ 📂Migrations

┣ 📂Provider

┃ ┗ 📜DateTimeProvider.php

^{A class to provide (and mock) the application's current date and time.}

┣ 📂Repository

^{Classes for implementing database queries and returning populated entities.}

┣ 📂Security

┃ ┣ 📂Voter

^{Classes for determining user permissions to routes.}

┣ 📂Service

┃ ┗ 📜BreadcrumbBuilder.php

^{A utility service for building breadcrumbs.}

┣ 📂Task

┃ ┗ 📜FlagStudentsTask.php

^{Runs a periodic cron job which flags students based on course instance configurations}

┣ 📂Twig

┃ ┗ 📜AppExtension.php

^{Custom Twig functions are created here, namely the renderRisk() function which renders SurveyQuestionResponseRisk subclasses on the webpage}

┗ 📜Kernel.php

^{The Symfony kernel which configures bundles, the symfony container and routes.}

📦templates

^{Twig view templates for forms, risk, and pages are here.}

┣ 📂course

^{Course page HTML view templates.}

┣ 📂form

┃ ┗ 📜custom_types.html.twig

^{HTML view template partials for custom forms.}

┣ 📂lab

^{Lab page HTML view templates.}

┣ 📂risk_summary

^{HTML view template partials for rendering SurveyQuestionResponseRisk objects.}

┣ 📂security

^{Login page HTML view templates.}

┣ ...

┗ 📜macros.html.twig

^{Common template partials encapsulated as macro functions.}

📦tests

^{Classes for unit and functional tests.}

📜.env

📜.env.test

^{Environment variables are defined in these files.}

📜.symfony.cloud.yaml

^{Symfony cloud configuration for hosting the evaluation app.}

📜Makefile

^{Contains aliases for development commands.}

📜README.md

📜composer.json

^{Contains PHP dependencies for backend code.}

📜docker-compose.yml

^{Contains docker compose script for database container creation.}

📜package.json

^{Contains node dependencies for frontend code.}

📜php.ini

^{PHP configuration for the project.}

📜phpunit.xml.dist

^{PHPUnit configuration for the project.}

📜webpack.config.js

^{Webpack configuration for building frontend assets.}

Symfony Bundle Code vs Project Code

Some code is automatically generated by particular Symfony bundles. All code which has been created / modified by myself is annotated with a comment at the top containing:

• The file name
• Gareth Sears - 2493194S

Testing

All automated tests are located in the tests folder. Subfolders correspond to subfolders in the src folder. The naming convention *Test.php is used, where * is the class name under test. The test runner is phpunit.

You can run the full test suite using the command make test/all.

Coverage of automated tests can be found in the coverage folder, which is generated using make test/coverage.

Manual acceptance tests are defined and documented in docs/AcceptanceTests.pdf.

Unit tests

Unit tests can be run using the make test/unit command. These unit tests use mocks to ensure each test is self contained.

This suite currently tests:

• Containers classes. These are responsible for calculating student risk based on their lab responses and performing sanity checks on grouped data (for example, ensuring course start dates are before end dates).
• Entity classes. These are the ORM classes and contain some important data validation checks.
• Security, which are the voter classes which are used to make elaborate permission checks in controllers using database queries.

Functional tests

Functional tests can be run using the make test/functional command. These are integration tests which perform database transactions.

The DataFixtures/EntityCreator.php class is used to generate test specific entities and any transactions are 'rolledback' after each test using the dama/doctrine-test-bundle.

All functional tests inherit from the FunctionalTestCase.php abstract class, which created to provide useful utility functions and access to essential services.

This suite currently tests:

• Route permissions and security handling in the Controller classes. This is done by automating logins and page navigation and testing if (in)valid responses are given.
• Entity classes which use annotation hooks to run methods during a database transaction.
• Repository classes, whose methods are responsible for querying the database and fetching entities.

Additional Documentation

Over the project's lifecycle, many processes were documented which could not be fully contained in the project's report. These are located in the docs folder and are referenced within the report.

Copyright

Copyright 2020, Gareth Sears, All rights reserved.