On Fire 🔥 - the cheerful productivity app API

This repository contains the ReSt API backend to On Fire 🔥 - the cheerful productivity app, developed for the Advanced Front-end specialization at Code Institute.

Developer: Dr. Sylvia Blaho

• Deployed API
• Front end GitHub repository
• Front end deployed app

See the development progress and further plans on the Project Kanban board.

Table of contents

• Database structure
  • Database
  • Data models
    • Comment model
    • Profile model
    • Task model
    • Watchers model
    • User model
  • Future features
  • Code features
    • Regular testing
    • Security
• API endpoints
• Testing
• Technologies used
  • Languages used
  • Frameworks used
  • Other dependencies used
  • Tools used
• Deployment
  • Prerequisites
  • Fork the repository
  • Deploy in the development environment
  • Deploy to production
    • Pre-deployment steps
    • Steps on Heroku
• Credits
  • Code credits
  • Related advice
  • Study/lookup sources
  • Readmes

Table of contents generated with readme-toc

Data structure

Database

Neon, a serverless Postgres database was used for Production, while the built-in SQLite dababase for used for API development & testing.

Data models

The diagram below shows the custom models for this project, along with the User model by Allauth (only the fields that are utilized in this project are shown on the User model below).

Individual field names, types and and their specifications are also shown.

The assessment criteria specify "a minimum of ONE custom model" for the MVP. The current implementation has 2 heavily customized models (Profile and Task), and 2 models based on the walkthrough project, which are slightly customized in the way they are used (Comment and Watchers).

Comment model

The Comment model is based on the walkthrough project, but 2 more extra fields are added to the serialzer: the first and last name of the owner's profile. This is used for conditionally rendering the user's name on the Front End depending on whether a firstname and lastname is filled in in their profile (the username is always present).

1. show first and last name if both are available
2. show first or last name if either are available
3. show username if neither are available

In some cases, 1. is shortened to only show the first name even if a last name is available.

Profile model

The Profile is heavily customized compared to the walkthrough project: not only are many more fields specified in it, but the extra fields specified in the serializer also work in a different way.

These are not only used for filtering in the API, but also for in custom hooks in the frontend that refresh individual components of the Task List pages without reloading the page.

Filtering based on the extra fields in the profile serializer forms the frame of displaying tasks on 3 different pages in the frontend.

Task model

The task model is the most extensive one of the app – unsurprisingly, since its primary purpose is tracking tasks. It is based on the Post model of the walkthough project, but it differs significantly in the number and type of fields it has, how fields relate to other models, how they are configured and how they are used in the frontend.

The Task model has 2 fields that relate to the User model: in addition to owner (the user creating the task), an assignee can also be spefcified. This is extensively used for filtering and presenting data in the frontend.

A further difference is that tasks should remain intact even when their creator (owner) or assignee are deleted (e.g., when a team member leaves an organization). In this case, the respective fields for the deleted user are set to null. Accordingly, the owner and assignee fields are allowed to be null.

A due_date field is added to the model. This is used to indicate overdue tasks in the frontend with a range of 🔥 emojis that features throughout the app branding (the longer the due date is in the past, the more 🔥 emojis appear on a task).

The status field is restricted to a pre-defined range, and it is used to automatically sort tasks into the corresponding columns in the frontend.

The priority field is also based on a pre-defined range, and is used to automatically change the color scheme of individual tasks in the frontend.

As described in the Frontend documentation, image upload is optional and there is no placeholder image added to tasks without images. These improvements are reflected in the Task model and the tasks serializer.

Watchers model

This model is based on Like in the walkthrough project, but it has additional uses beyond statically filtering tasks: changes in Watchers instances trigger custom hooks refetching Profile and Task data without refreshing the page in the frontend.

User model

The standard User model is extended by profile_lastname and profile_firstname fields in the task_manager_api serializer. These fields are used to render users' names thourhout the app, as described in the Comments model section.

Future features

The Project model has not been part of the MVP, as development time for the 1st version of this project was only 3 and a half weeks. It was thus relegated to version 2 of the app.

Code features

Regular testing

Code was manually tested and validated throughout development. At the end of the development process, a final, comprehensive round of testing and validating was completed. The results are detailed in TESTING.md.

Adequate

Apart from making sure that the app functions as intended, I have also taken special care to make sure the code is well organized and appropriately commented. Since I am just becoming familiar with Django REST Framework (and dealing with executive functioning issues), I have erred on the side of "more is more" for code comments and docstrings for methods that were new to me.

Security

Sensitive information such as secret keys, Cloudinary URL and Database URL are stored in environment variables that are never committed to GitHub. They are not sent through unsecured channels, and not written down on paper.

All passwords are stored in a password manager, and not written down in plain text electronically or on physical paper.

Unfortunately, the infrastructure for project submission at Code Institute requires the admin credentials to be submitted in plain text.

API endpoints

The available endpoints, paths and actions are described under Manual feature testing inTESTING.md for details.

Testing

See the document TESTING.md for details.

Technologies used

Languages used

• Python 3.12.2

Frameworks used

• Django
• Django ReSt Framework

Other dependencies used

• asgiref – asynchronous communication between web apps & servers
• cloudinary – storing images
• dj-database-url – use an environment variable to configure databases
• dj-rest-auth – access management
• django-allauth – access management
• django-cloudinary-storage – interaction between Django and Cloudinary
• django-cors-headers – CORS (Cross-Origin Resource Sharing) headers in responses
• django-filter – queryset filtering
• djangorestframework-simplejwt – JSON Web Token authentication
• gunicorn – HTTP server for deployment
• oauthlib – framework-agnostic OAuth implementation
• Pillow – image processing
• psycopg2 – PostgreSQL database adapter
• PyJWT – encoding and decoding JWT tokens
• python3-openid – support for the OpenID decentralized identity system
• pytz – timezone calculation
• requests-oauthlib – OAuthlib authentication support for Requests
• sqlparse – SQL parser
• urllib3 – HTTP client

Tools used

• CI Python Linter – validate Python code
• Git – version control
• GitHub – store the source files
• GitHub Desktop – GitHub UI
• GitHub Issues – feature management, bug tracking
• GitHub Projects – project management
• GitHub TOC generator – automatically generate a Markdown TOC
• GitHub web editor
• GitPod – Integrated Development Environment
• Google Sheets – planning user stories
• Heroku – host the production version of the app
• Lucidchart – make the ERD
• markdownlint extension for VS Code – Markdown linting & style checking
• Neon – serverless Postgres database
• Preview – cropping and annotating images
• Shields.io – add badges to README
• Slack – mentor communication
• Typos spell checker for VS Code

Deployment

The following instructions describe the deployment process with the tools used for this project. Of course, you can choose other tools/providers for the individual functions described below, e. g., a different Postgres database instead of Neon, or a different development environment instead of GitPod. Naturally, detailed instructions are only provided for the tools used in this project.

Prerequisites

• GitPod (or another IDE)
• Python 3.12
• pip
• git
• Neon (or another Postgres database)
• Cloudinary (or another media hosting provider)
• Heroku (or another could platform)
• Dependencies listed in requirements.txt

Warning

The setup has been known to be prone to version conflicts, so use the exact versions specified in requirements.txt

Fork the repository

You can fork the repository by following these steps:

1. Log in to GitHub (if you don't have a GitHub account yet, you can create one for free).
2. Navigate to the project website https://github.com/blahosyl/task-manager-api.
3. Click on Fork in the upper right part of the screen.
4. On the next page you have the possibility to change the repository name. To do this, simply write your desired name in the text field in the center part of the screen. You can also leave the name as it is.
5. Click Fork in the bottom right part of the screen.

Tip

If you do rename the repository, make sure to keep the GitHub naming conventions in mind.

Deploy in the development environment

1. Open the repository in a new workspace in GitPod. GitPod will automatically run the Python virtual environment for you. If you're using a different development environment, see this documentation.

2. Install the required dependencies:

   pip3 -r requirements.txt.
   

3. To store access credentials and other secrets, create a file called env.py in your top-level project directory. Before adding any content to it, add env.py to .gitignore and commit your changes. This will prevent the contents of env.py from being pushed to the Git repository.

4. Add the following information to your env.py file:

   • CLOUDINARY_URL - you can find this in your Cloudinary console under API Keys
   • DATABASE_URL
   • ALLOWED_HOST - the URL of your local server
   • CLIENT_ORIGIN_DEV - the URL of your Frontend development server
   • SECRET_KEY
   • DEV - set this value to '1' in your development setup. This is used to determine if the app runs in Development or Production mode

5. In settings.py, add your GitPod workspace URL to ALLOWED_HOSTS

6. Run a migration to create your database tables:

   python manage.py migrate
   

7. Create a superuser (make sure you save the username and password you use here):

   python manage.py createsuperuser
   

8. Run the development server

   python manage.py runserver
   

Deploy to production

Pre-deployment steps

Make sure to complete the following pre-deployment steps in your development environment, especially if you made changes to the project:

1. (Re-)create a list of requirements by going to the terminal and typing pip3 freeze > requirements.txt. This populates your requirements.txt file with the list of required files.
2. In settings.py, make sure DEBUG=False (or set conditionally based on the value of DEV)
3. Commit and push your changes to GitHub.

Steps on Heroku

1. Log in to your Heroku account (or create a new one if you have not done so yet).
2. Create a new Heroku app by selecting your region and app name.
3. Under Settings > Config Vars in Heroku, add the following variables:
   • CLOUDINARY_URL - you can find this in your Cloudinary console under API Keys
   • DATABASE_URL
   • SECRET_KEY
   • ALLOWED_HOST - your Front End app URL
   • CLIENT_ORIGIN_DEV - the URL of your Frontend development server (if you want to use the deployed app with your Frontend Dev setup)
   • CLIENT_ORIGIN - the URL of your deployed Frontend app
   • DISABLE_COLLECTSTATIC – set value to 1 (this tells the deployed app not to collect static files)
4. Under Deploy > Deployment method in Heroku, select GitHub and connect Heroku to your GitHub account.
   • Type in your repository name, then click Search.
   • When your repository appears, click Connect next to it.
5. Under Deploy > Manual deploy in Heroku, select Deploy branch to deploy manually.
   • Once the process is finished, the following message will appear:
     Your app was successfully deployed
   • Click View under the message, and a new tab will appear with your deployed app.
6. (optional) Under Deploy > Automatic deploy in Heroku, select Enable Automatic Deploys if you want your app to be rebuilt each time you push to the main branch of your GitHub repository (but make sure your settings.py file always has DEBUG=False when you do).

Credits

Code credits

This project was developed on the basis of the DRF-API by Code Institute.

Tutor Thomas suggested changing the due_date field in my Tasks model to a DateField from a DateTimeField.

Related advice

Study/lookup sources

• Django model field reference
• Django on_delete options
• Django REST Framework generic API views
• Django REST model field reference

Readmes

• Creating your first README with Kera Cudmore by Code Institute
• Creating your first README by Kera Cudmore
• Bully Book Club by Kera Cudmore
• Bodelschwingher Hof by Ana Runje
• Travel World by Pedro Cristo
• Sourdough Bakes by Siobhan Gorman
• Horizon Photo by Rory Patrick Sheridan
• BackeStock by Amy Richardson
• American Pizza Order System by Iasmina Pal
• Neverlost by Rory Patrick Sheridan
• EastStr by Nathan Surgenor
• League Hub by MikeE94
• Tick it by Jamie King
• The README of my first Code Institute project
• The README of my second Code Institute project
• The README of my third Code Institute project
• The README of my fourth Code Institute project