Architecture

Languages and Framework

Our application will be created with the Django framework (Django 5.1). Our code will be written in Python (3.13.0).

Building and Package Manager

The application will utilize Pipenv for package management. As an enhanced version of pip, it ensures the simplicity of installing, upgrading, and managing the dependencies throughout the development of the project. Pipenv the functionality of automatic virtual environment management from virtualenv, this will allow for the application's dependencies to be isolated, meaning that it will help avoid possible dependency conflicts. Pipenv will make managing the Django dependencies more efficient and secure.

Workload Distribution

Ankit and Trevor will handle the frontend work. Backend development and API usage will be handled by Colin and Cade. Thomas will handle the database connection and data storage.

Deployment

Deployment is fairly simple. Once the DJANGO_SETTINGS_MODULE is set up to work with WSGI, you run a new thread using gunicorn (file).wsgi. Once this is done, all it takes to update is a git pull and re-run the server. Thomas Kareka will be running the website using a personal linux server running Ubuntu 24. (should be accessible through direct ip, don’t have a domain to host it at) While it would be possible to set up a script to reboot and pull from our github repo daily, this most likely isn't necessary. For testing purposes, a Django debug server is very similar to a server in production.

Virtual Machines and Containers

A virtual machine is not necessary. While Python is mostly universal, Gunicorn is not, but we have a server ready to deploy to. As a backup, we can use PythonAnywhere. A container is also not necessary, but at the very least, we should be using a Python virtual environment.

SPA or Traditional

Our application will not be a SPA. Although a SPA is possible with Django, the design that we created (as seen in the Design section of the wiki) involves the use of multiple pages. The user will navigate to different pages on the app, which each have a specific functionality.

URL Space

Django URLs follow the format /app/page/subpage, using <type:var> for pages where data must be passed through.

/coldcall/ - Main page
/coldcall/<int:pk> - Main page with course selected
/coldcall/<int:pk/>/randomizer - Student Randomizer
/coldcall/student/<int:pk> - Student metrics page
/coldcall/addstudents/manual - Add Student (Manual)
/coldcall/addstudents/import - Add Students (Import)
/coldcall/addstudents/addcourse - Add Course
/coldcall/editclasses/<int:pk>/<int:pk/>/manual - Student Editor (Manual)
/coldcall/editclasses/<int:pk>/<int:pk>/csv - Student Editor (CSV)

It should be possible to change the template django uses for each view by getting and parsing the user's User-Agent.

REST API

• GET /coldcall/
  • Description: Retrieve a list of all courses.
  • Method: GET
  • Response: Returns a list of all courses with course names and IDs.
• GET /coldcall/int:pk/
  • Description: Retrieve details of a specific course by its ID.
  • Method: GET
  • Parameter: pk (integer): ID of the course.
  • Response: Returns detailed information about the course, including students and metrics.
• GET /coldcall/int:pk/randomizer/
  • Description: Randomly select a student from a course and display their details.
  • Method: GET
  • Parameter: pk (integer): ID of the course.
  • Response: Returns randomly selected student details and their history.
• GET /coldcall/student/int:pk/
  • Description: Retrieve metrics and details of a specific student by their ID.
  • Method: GET
  • Parameter: pk (integer): ID of the student.
  • Response: Returns details, attendance, and rating history of the student.
• POST /coldcall/addstudents/manual/
  • Description: Add a new student to a specific course manually.
  • Method: POST
  • Request Body:
    • first_name (string): First name of the student.
    • last_name (string): Last name of the student.
    • seating (string): Student’s seating arrangement.
    • class_id (integer): The ID of the course.
  • Response: Returns the newly created student’s details.
• POST /coldcall/addstudents/import/
  • Description: Import multiple students into a course via CSV or spreadsheet.
  • Method: POST
  • Request Body:
    • csv_data (file): CSV or spreadsheet containing student data.
  • Response: Imports and returns a confirmation of the import with any errors encountered.
• PUT /coldcall/editclasses/int:course_pk/int:student_pk/manual/
  • Description: Update a student's information manually within a course.
  • Method: PUT
  • Parameters:
    • course_pk (integer): Course ID.
    • student_pk (integer): Student ID.
  • Request Body:
    • first_name (string): First name of the student.
    • last_name (string): Last name of the student.
    • seating (string): New seating arrangement.
  • Response: Returns the updated student details.
• PUT /coldcall/editclasses/int:course_pk/int:student_pk/csv/
  • Description: Update a student’s details by re-importing a CSV with updated information.
  • Method: PUT
  • URL Parameters:
    • course_pk (integer): Course ID.
    • student_pk (integer): Student ID.
  • Request Body:
    • csv_data (file): CSV with updated student details.
  • Response: Returns a confirmation of the update and any errors.

Views

Web Base

This is the main screen that the user will see after loading/creating a database. It features a scrollable list of all the students, with a preview of their data. Clicking on a student then opens a more detailed view of their information. The navigation bar at the top has three features: left will open the menu, center shows the current course and provides a dropdown, where the user can add/drop courses, and the top right opens the cold call feature.

Web Student Metrics

This screen will be prompted to the user when they click on a student in the Web Base. It provides a quick summary of the student for the user, providing them with their prior calls, average rating, bar graph of the students history, and a list of all of all previous calls. Additionally, there are "Last Student" and "Next" student buttons to allow for the user to go through the list of students with ease. There is also an edit button to edit the current student selected in the top right of the screen and a close button to go back to the main screen.

Web Add Student (Manual)

The user can add a student manually on this page by entering the respective student’s information. The user must enter the student’s first name, last name, and seating arrangement. The user may also enter the student’s prior calls and rating, but both of these are optional.

Web Student Editor (Manual)

This screen is prompted to the user when they click the edit button on the student metrics page. The user is prompted with multiple options to change things about the current student that is selected in the student metrics page. There are two specific areas of info stored for each student, the first being the ratings that they have received throughout the course and the other being personal info. The user has the ability to change the rating from any specific day for said student along with their first name, last name, and seat.

Web Student Editor (CSV)

This screen is prompted to the user when the change the screen to the second option in the Student Editor. Here, the user is able to get a more advance view of the current CSV file being stored and used for the class. The user has the ability of uploading a new CSV file with any update that they have with the course. Formatting is provided in this page to ensure that the user will not have any issues or error occur when uploading their new file.

Web Menu

The menu pops out from the right and darkens the inactive window for better contrast. It can be closed either by clicking the grey area or clicking the close menu button. Save To and Import From open a pop up window when clicked, allowing the user to choose from the device's internal file manager, OneDrive (need to look into how the API for this works), and Text (from clipboard). (Import From is used to transfer between devices: data is automatically loaded from last database used when opening the app)

Web Add Students (Import)

Allows the user to paste from their clipboard, or automatically import from an existing spreadsheet of student names, and data if applicable. (data format here is undetermined, using rating_unixtimestamp as a placeholder). Only student name is required. Clicking the X removes them and all of their associated data (with a confirmation popup). Clicking the edit button allows the user to edit student information, such as their name and seat position.

Web Add Course

Allows the user to add a new course. The user will enter the course name, start date, and end date. This pop up window is opened when the add course button is selected from the courses dropdown. The background is greyed out to emphasize the window. The window can be exited be by clicking the x in the top right or by clicking outside of the window.

Web Student Randomizer

This page is shown after the professor has chosen to randomly select a student and a student is chosen. This page shows the student's name, seat number, prior calls, average rating, as well as buttons for the professor to rate the student's performance as either -/5 stars, absent, un/under prepared, or a skip button. After a rating or button is clicked an option to choose a new student will appear.

Database Schema

We will be using SQLite for our database, interfacing through django.db.models. Users will simply use the default configuration from django.contrib.auth, as not much else needs to be stored for user authentication itself. (just user, name, and hashed password).

Each model will cascade down through a many-to-one system, all leading back to the original user.

Class(models.Model):

• professor_key: Foreign key reference to the user in which the class belongs to, should delete all nested data if deleted. (models.CASCADE)
  
• class_name: String of characters limited to 200 characters. (models.CharField)
  

Student(models.Model):

• class_key: Foreign key reference to class that the student is part of.
  
• first_name: CharField limited to 100 characters.
  
• last_name: CharField limited to 100 characters.
  
• seating: Stored using a CharField, has a list of potential seating arrangements using models.Field.choices, combination between front/back and left/center/right or none.
  The following could be used to minimize recalculating existing data or additional db calls on the class list page:
  
• total_calls: IntegerField
  
• absent_calls: IntegerField
  
• total_score: IntegerField (Average score would then be calculated from total_score/(total_calls-absent_calls))
  

StudentRating(models.Model):

• student_key: Foreign key reference.
  
• date: Date or UNIX timestamp in which the rating was created. (models.DateField)
  
• attendance: Was the student present when called on? (models.BooleanField)
  
• prepared: Another boolean to indicate whether the student was underprepared or not.
  
• score: IntegerField, limited between 1-5.
  

Common Queries

In Django, queries are handled through django.db.models. For example, to get the first 20 ratings from a student, you would import models.Student and return Post.objects.order_by("-date")[:20]. Retrieving a single object is also simple, through Student.objects.get(id=student_id). Saving changes to a database object requries retrieving it, modifying it, and simply calling Object.save().