Skip to content

Latest commit

 

History

History
705 lines (599 loc) · 45.1 KB

README.md

File metadata and controls

705 lines (599 loc) · 45.1 KB
Raw

Indøk NTNU


Logo

Table of Contents

Introduction

MIT License CI Code style code style: prettier codecov

Website for the students at Industrial Economics and Technology Management at NTNU Trondheim. Built with Django, Next.js, and a GraphQL API. Maintained by Rubberdøk NTNU.

Landing page Landing page

Features

  • 🏔 Book the luxurious cabins Oksen and Bjørnen
  • 💸 Register for upcoming events and purchase tickets through Vipps
  • 🎉 Find and apply for the ideal student organization at Indøk
  • 🔒 Simple login through Feide
  • 📝 Easily navigate through the archive of Indøk documents

Project Structure

  • frontend contains the indokntnu.no web application, written in TypeScript with React and Next.js.
    • src contains the source code of the frontend.
      • pages contains page components, where each file corresponds to a URL on the website. For example, pages/about/board.tsx is the component that is rendered at indokntnu.no/about/board. Files/folders in [brackets] are variables in the URL, so pages/about/organizations/[slug].tsx gives access to the slug variable in that page component, which is e.g. rubberdok in indokntnu.no/about/organizations/rubberdok.
      • components contains React components used to build up the website.
        • pages (under components) are components for specific pages. The folder structure here mirrors the folders in the top-level pages, so components for the pages in pages/events are in components/pages/events.
        • Other folders here are for components used across pages.
      • layouts contains React components that are part of the base website layout on every page, e.g. the navigation bar and footer.
      • graphql contains GraphQL requests that the frontend uses to talk to the backend API.
        • The folders here are grouped by backend app, so graphql/events contains queries/mutations for the backend app in backend/apps/events.
        • Each folder has:
          • queries.graphql for requests that only fetch data.
          • mutations.graphql for requests that change data.
          • fragments.graphql for GraphQL fragments: a selection of fields on one of our API types, that can be reused across different queries/mutations to ensure consistent types. Whenever you see a ...Fragment type from generated/graphql, that type has been generated from a fragments.graphql file.
      • generated contains output from code generation.
        • graphql.ts is the output from graphql-codegen, the tool we run with yarn generate. It reads our GraphQL schema (backend/schema.json), and our queries, mutations and fragments (from the graphql folder), to generate TypeScript types and data for making requests to our backend API.
      • types contains shared types used across the app.
      • theme contains customizations for Material UI, the styled component library we use for React.
        • components contains customizations for specific Material UI components.
      • lib contains functions defined by us to make it easier to work with some of our libraries.
      • utils contains utility functions.
    • .husky configures Husky, the tool we use for pre-commit hooks (checks that run on each Git commit).
    • content contains files for static content used by our React components.
    • cypress defines our Cypress end-to-end tests, which essentially involve a robot clicking through our website to check that everything works as expected.
    • public contains public files, such as images, served by our frontend.
    • package.json lists the TypeScript dependencies of the project, and also defines the scripts for use by Yarn. Running yarn installs the dependencies listed here, while running e.g. yarn dev runs the command in "scripts": ... "dev":.
    • .eslintrc.json configures ESLint, our linter (a tool to enforce code standards) for TypeScript.
    • .prettierrc configures Prettier, the tool we use to format our TypeScript code.
    • codegen.yml configures graphql-codegen, the tool we use to generate TypeScript code from our backend's GraphQL API schema and the .graphql files we write in our frontend. This is what runs in the yarn generate command.
    • tsconfig.json configures the rules TypeScript should enforce when type checking our code.
    • .env files define the environment variables for the different environments of the project (development, production, testing).
      • To override environment variables for your local development environment, add a .env.local file with your variables. This file is ignored by Git.
  • backend contains the backend server at api.indokntnu.no, written in Python with Django and Graphene.
    • api/auth contains the logic for authenticating users on their requests.
    • apps contains the different Django apps (essentially modules) for the backend. Each app follows this structure (or at least parts of it):
      • fixtures contains example data for local development, loaded through python manage.py loaddata initial_data.
      • migrations contains Django files for migrating (updating) the database after every change to a Django model in the app. Most of these are generated through the python manage.py makemigrations command, though some are custom-written for more complex updates of the database. The code in these files is what runs when you do python manage.py migrate.
      • admin.py configures what parts of the app should be shown in the Django admin panel.
      • apps.py configures the app.
      • constants.py contains constant values used by the app.
      • dataloader.py contains custom logic for loading data for particular GraphQL queries (read more here).
      • models.py defines the Django models of the app, which is how objects of the app are stored in the database.
      • mutations.py defines classes for each GraphQL mutation in the app's API (GraphQL requests that change data), and their arguments.
      • resolvers.py defines methods for resolving each GraphQL query in the app's API (GraphQL requests that only fetch data).
      • schema.py defines the GraphQL schema for the app's API. It imports the mutations and query resolvers from mutations.py and resolvers.py, and defines the types for the queries.
      • signals.py contains Django signals, which are functions that run on a specific trigger (e.g. when an object of a particular model is saved to the database).
      • tests.py contains tests of the app's logic.
      • types.py defines the GraphQL API types for models in the app. You can think of a type in this context as how an object is represented in our API (to our frontend), while a model is how it is represented in the database. An API type typically inherits from Graphene's DjangoObjectType and bases itself on the fields of its corresponding Django model. However, it can also add custom fields that are not on the database model, in which case it defines a resolve_[field_name] on the type with the logic for resolving that field.
    • config configures the Django project, and ties together the different apps.
      • settings contains Django settings for the project.
        • base.py has settings for every version of the project.
        • local.py has settings for local development of the project.
        • production.py has settings for the production environment (the live website) of the project.
      • urls defines the URL endpoints of the backend server. It follows the same file structure as settings.
      • schema.py defines the GraphQL schema for the whole API of the backend. It simply imports each app's schema from their schema.py files, and combines them.
    • decorators defines our custom Python decorators, which are the functions used with the @ syntax.
    • entrypoints contains scripts for running the backend, used by Docker and our Continuous Integration pipelines.
    • requirements list the Python dependencies of our project, to make it easier to install with e.g. pip install -r requirements/local.txt.
      • base.txt contains the main dependencies for all versions of the project.
      • local.txt includes our Python formatter and linter for development.
      • production.txt includes a library for logging production errors to Sentry, our error logging service.
    • static contains static content served by our backend.
    • templates contains Django templates, which is HTML but with slots for inserting values in Python.
    • utils contains shared utility classes and functions for use by our backend.
    • schema.json is a JSON representation of the backend's GraphQL API schema defined in our schema.py files. It is generated with the python manage.py graphql_schema command, and can then be used by our frontend to generate TypeScript code for interacting with our API. So you can essentially think of schema.json as a language-agnostic "translation step" for letting the TypeScript frontend use the API types from our Python backend.
    • mypy.ini configures MyPy, a type checker for Python.
    • pyproject.toml configures Black, the tool we use to format our Python code.
    • tox.ini configures flake8, our linter (a tool to enforce code standards) for Python.
    • .env files contain the environment variables for the different environments of the project (development, production, testing).
      • To override environment variables for your local development environment, add a .env file with your variables. This file is ignored by Git.
  • .gitignore tells Git which files should not be included in the repository (these are grayed out in VSCode's file explorer).
  • docker-compose.yml configures the Docker containers that can be run with the docker compose command. Our frontend and backend also have a Dockerfile each for configuring their Docker containers.

Project Setup

With Docker below describes how to set up the project fully in Docker. This may not work perfectly for everyone, particularly those using Windows - they may instead wish to follow the steps under Without Docker, but DOCKER IS RECOMMENDED FOR EVERYONE. Finally, VSCode describes how to configure your development environment in the VSCode editor.

With Docker (Recommended)

  1. Download, install and start Docker Desktop: https://www.docker.com/products/docker-desktop
  2. In the terminal, move to where you want to store the project (easiest is just where you are when you open the terminal)
  3. Type git clone https://github.com/rubberdok/indok-web.git
    • This creates a new folder named indok-web, which contains the project
    • If you don't have git you will need to install it
  4. Type cd indok-web to move into the new folder
  5. (optional, but extremely recommended) Set up the backend locally, to get linting, auto-complete and environment variables
  6. (optional, but extremely recommended) Set up the frontend locally, to get pre-commit hooks, linting, auto-complete and environment variables
  7. Type docker compose build to build the project
  8. Type docker compose up to run the frontend, backend and database
  9. Open a new terminal, and navigate back to indok-web
  10. Type docker compose exec backend python manage.py migrate to update the database
  11. Type docker compose exec backend python manage.py loaddata initial_data to load example data into the database
    • Only works if you followed the backend env setup from step 5

The frontend runs on http://localhost:3000, and the backend on http://localhost:8000. The GraphQL API endpoint is http://localhost:8000/graphql, and the Django panel is at http://localhost:8000/admin.

If you want to close the app, press Ctrl + C in the terminal running Docker, or type docker compose down inside the indok-web folder in another terminal. To start the app again, type docker compose up, also in the indok-web folder (and make sure Docker Desktop is running!). If you want to clear the database, go to the Volumes tab in Docker Desktop, and delete indok-web_postgres_data.

Without Docker

(Think this is no longer true) Some users, particularly those using Windows, may have issues running the app through Docker. Some functionality such as hot reloading (which drastically improves developer experience) may only work when you have the whole project in WSL (Windows Subsystem for Linux, which is what Docker on Windows uses). Therefore, you may prefer to run the project without Docker — in that case, follow the below steps to set up the frontend, backend and database locally.

Before following the steps below, make sure to clone the project with Git:

  1. In the terminal, move to where you want to store the project (easiest is just where you are when you open the terminal)
  2. Type git clone https://github.com/rubberdok/indok-web.git
    • This creates a new folder named indok-web, which contains the project
  3. Type cd indok-web to move into the new folder
  4. If using VSCode, you can type code . to open the current folder in VSCode

Database

The project uses PostgreSQL as its database. Even when running the frontend and backend outside of Docker, we still recommend running Postgres through Docker, since you don't need hot reloading there and it makes the setup simpler.

To set up PostgreSQL in Docker, follow these steps:

  1. Download, install and start Docker Desktop: https://www.docker.com/products/docker-desktop
  2. Open the indok-web folder in VSCode
  3. Make a new file called .env inside backend
  4. Paste the following line in that file, and save:
DB_HOST=localhost
  1. Navigate to indok-web in the terminal (cd indok-web)
  2. Type docker compose up postgres

Now Postgres should be up and running! Leave the terminal window open to keep the database running in the background.

If you want to close the database, press Ctrl + C in the terminal running Postgres, or type docker compose down inside the indok-web folder in another terminal. To start Postgres again, type docker compose up postgres, also in the indok-web folder (and make sure Docker Desktop is running!). If you want to clear the database, go to the Volumes tab in Docker Desktop, and delete indok-web_postgres_data.

If you still want to run Postgres without Docker, download and install it from here instead: https://www.postgresql.org/download/. Then follow steps 2-4 as above.

Backend

  1. Download and install pyenv (Python version manager): https://github.com/pyenv/pyenv#installation
  2. Type pyenv install --list | grep " 3.9" to get the list of available Python 3.9 versions
    • If on Windows, type pyenv install --list | findstr " 3.9" instead
  3. Type pyenv install 3.9.X, where X is the latest version found from the previous step
  4. Type pyenv global 3.9.X, where X is the same as the previous step
    • If you do not want to use Python 3.9 globally, type pyenv local 3.9.X instead (make sure you are in the indok-web folder when you do this)
    • Type python --version to verify that it has been set to 3.9.X
  5. Type cd indok-web to move into the project folder (if you weren't already there)
  6. Type python -m venv venv
    • This sets up a Python virtual environment, to isolate this project from others
  7. Type source venv/bin/activate to activate the virtual environment
    • If on Windows, type .\venv\scripts\activate instead
  8. Type cd backend to move into the backend folder
  9. Type python -m pip install -r requirements/local.txt to install dependencies
  10. Ask the project maintainers for dev environment variables (not strictly required, but step 14 will not work without this)
    • If you're a member of Rubberdøk:
      • Go to the #dev channel in Slack
      • Find the pinned post with dev environment variables
      • Copy the variables for backend/.env into your own .env file in indok-web/backend (make sure not to overwrite the DB_HOST variable from the database setup)
  11. Set the environment variable DJANGO_READ_DOT_ENV_FILE to true
    • On Mac/Linux:
      • Type code ~/.zshrc to open the zsh config in VSCode
        • If code doesn't work, try open ~/.zshrc to open it in another text editor
      • Paste this line somewhere in that file: export DJANGO_READ_DOT_ENV_FILE=true
      • Save the file, and re-open the terminal
    • On Windows (with the PowerShell terminal):
      • Type code $profile to open the PowerShell config in VSCode
        • If code doesn't work, type echo $profile and open that file in some other text editor
      • Paste this line somewhere in that file: $env:DJANGO_READ_DOT_ENV_FILE = "true"
      • Save the file, and re-open PowerShell
  12. Type python manage.py runserver to run the backend server
    • If it fails, make sure that you:
      • are in the indok-web/backend folder
      • have your virtual environment active
      • have the database running
  13. Open a new terminal (leave the previous terminal open to keep the server running!)
    • Type cd indok-web to move into indok-web (or cd .. if you were put in indok-web/backend)
    • Type source venv/bin/activate (Mac) or .\venv\scripts\activate (Windows) to re-activate the virtual environment in this new terminal
    • Type cd backend to get back to the backend folder
  14. Type python manage.py migrate to update the database with our backend models
  15. Type python manage.py loaddata initial_data to load example data into the database
    • This also creates an admin user with username admin and password admin123

Now the backend should be running at localhost:8000! You can check out the GraphQL API at localhost:8000/graphql, or use the Django admin panel at localhost:8000/admin (log in with the admin user from step 14).

If you want to close the backend, press Ctrl + C in the terminal where it runs. To start it again:

  1. Move into the indok-web folder (cd indok-web)
  2. Activate your virtual environment
    • On Mac: source venv/bin/activate
    • On Windows: .\venv\scripts\activate
  3. Move into the backend folder (cd backend)
  4. Type python manage.py runserver
  5. If you need to run migrations:
    • Open a new terminal, and repeat steps 1-3
    • If you've made changes to Django models and want to generate new migrations: python manage.py makemigrations
    • Run migrations with python manage.py migrate

Frontend

  1. Download and install nvm (Node Version Manager): https://github.com/nvm-sh/nvm#installing-and-updating
    • If on Windows, install nvm-windows instead: https://github.com/coreybutler/nvm-windows/releases
      • Scroll down on that page to find nvm-setup.exe, and download it
      • Open the terminal as administrator (PowerShell/Command Prompt/Windows Terminal)
      • Use cd to navigate to where you downloaded the .exe file (e.g. cd downloads)
      • Type .\nvm-setup.exe, and go through the installer
    • Type nvm version in a new terminal to check that it was installed correctly
  2. Type nvm install --lts in the terminal to install the current long-term support (LTS) version of Node.
  3. Type nvm use --lts
    • If on Windows, you may have to run the terminal as administrator
  4. Open the indok-web folder in VSCode, and create a file called .env.local
  5. Ask the project maintainers for dev environment variables
    • If you're a member of Rubberdøk:
      • Go to the #dev channel in Slack
      • Find the pinned post with dev environment variables
      • Copy the variables for frontend/.env.local into your own .env.local file in indok-web/backend
  6. Type cd indok-web/frontend to move into the frontend folder (or just cd frontend if you were already in indok-web)
  7. Type npm install -g yarn
    • This installs Yarn, which we use to manage dependencies in the frontend
  8. Type yarn to fetch dependencies
  9. Type yarn dev to run the frontend

Now the frontend should be running at localhost:3000! You can check it out in the web browser.

If you want to close the frontend, press Ctrl + C in the terminal where it runs. To start it again, type yarn dev inside indok-web/frontend (if dependencies have changed, you may have to run yarn first).

Troubleshooting

If you are having fetching errors try changing, NEXT_PUBLIC_INTERNAL_API_URL=localhost:8000 to NEXT_PUBLIC_INTERNAL_API_URL=http://127.0.0.1:8000

VSCode

First of all, we recommend installing the following extensions:

Next, open the indok-web folder in VSCode, create a folder called .vscode at the top level, and a settings.json file inside that. Paste the following in it:

{
  // Auto-formats code on save
  "editor.formatOnSave": true,

  // Configures Prettier, our formatter for TypeScript
  "[html][css][json][jsonc][yaml][javascript][javascriptreact][typescript][typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  // Configures ESLint, our linter for TypeScript
  "eslint.workingDirectories": ["frontend"],
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },

  // Configures Black, our formatter for Python
  "python.formatting.provider": "black",
  "python.formatting.blackArgs": ["--config=backend/pyproject.toml"],

  // Configures flake8, our linter for Python
  "python.linting.flake8Enabled": true,
  "python.linting.flake8Args": ["--config=backend/tox.ini"],

  // Allows the Python VSCode extension to suggest correct auto-import paths when having the project open in indok-web
  "python.analysis.extraPaths": ["backend"]
}

Finally, if you're on Mac, we recommend pressing Cmd + Shift + P, searching for "shell command", and clicking Shell Command: Install 'code' command in PATH. This lets you open your current folder in the terminal, using code ..

Using test users

The python manage.py loaddata initial_data command used in the setup above sets up one admin user and two test users:

Username Password Indøk
eva_student 098asd true
asbjorn_elevg 098asd false
admin admin123 super

To log in as one of these test users when testing out the frontend locally, click "Other login alternatives" on the Feide login screen, then "Feide Test Users".

Development Workflow

An outline of how a developer may work with this project:

  • Move to indok-web in the terminal (cd indok-web)
  • If you are on the main branch, pull the latest updates
    • In the terminal:
      • Type git status to see which branch you are on
      • If you're not on the main branch but want to move back to it, type git checkout main
      • Type git pull to get the latest updates
    • In VSCode:
      • Check which branch you are on in the bottom left corner of the window
        • To change branch, click it and select e.g. main
      • Go to the Source Control tab on the left
      • Click ... -> Pull
  • Run the frontend, backend and database
    • With Docker:
      • Have Docker Desktop open, and type docker compose up inside indok-web
        • You may sometimes have to do docker compose build first
      • If the backend complains about unapplied migrations:
        • Open a new terminal in indok-web
        • Type docker compose exec backend python manage.py migrate
    • Without Docker (one terminal for each, in the indok-web folder):
      • Database (still with Docker):
        • Type docker compose up postgres
      • Backend:
        • Activate your Python virtual environment
          • Mac: type source venv/bin/activate
          • Windows: type .\venv\scripts\activate
          • If you've followed the steps in the #dev channel in the Rubberdøk Slack: simply type venv
        • Type cd backend to move into the backend folder
        • Type python manage.py runserver
        • If it says you have unapplied migrations:
          • Open a new terminal in indok-web, activate your virtual environment again, then cd backend
          • Type python manage.py migrate
        • If it complains about missing dependencies:
          • Close the server (Ctrl + C)
          • Type pip install -r requirements/local.txt to install dependencies
          • Type python manage.py runserver again
      • Frontend:
        • Type cd frontend to move into the frontend folder
        • Type yarn dev to start the app
        • If it complains about missing dependencies:
          • Close the app (Ctrl + C)
          • Type yarn to install dependencies
          • Type yarn dev again
  • Open another terminal, and move back to indok-web
  • Open the project in VSCode, or your favorite code editor
    • Type code . to open the current terminal folder in VSCode
  • Create a new Git branch for your changes
    • In the terminal:
      • Type git checkout -b add-example-feature to create a new Git branch called add-example-feature
        • Replace this name with a short, descriptive name for your branch!
    • In VSCode:
      • Click the branch name in the bottom left of the window, then Create new branch...
  • Make your changes to the code!
    • If you want to update a page on the website:
      • Navigate to the file in frontend/src/pages that matches the URL of the page you want to update
      • Update the page component as you wish
        • If what you want to change is not shown in the page component, it's probably in a sub-component
          • Sub-components for a specific page are in frontend/src/components/pages/...
            • For example, components for event pages are in components/pages/events
          • In VSCode, you can move to a sub-component on a page by right-clicking it in the HTML of the page component, and clicking Go to Definition
    • If you want to add/update a GraphQL query/mutation to fetch/change data from the backend:
      • Find the queries.graphql / mutations.graphql file in the appropriate feature folder under frontend/src/graphql
      • Add/change your query/mutation
        • Use a fragment from fragments.graphql with the ...MyFragment syntax if you want to use the same fields as other queries/mutations
      • Generate TypeScript code for your query/mutation
        • cd into frontend, and type yarn generate
      • At the top of the React component file where you want to use your query/mutation:
        • For query: import { useQuery } from "@apollo/client";
        • For mutation: import { useMutation } from "@apollo/client";
        • import { [MyQuery/MyMutation]Document } from "@/generated/graphql";
      • Inside the component:
        • For query:
          • const { data, loading, error } = useQuery([MyQuery]Document);
            • If the query has variables, add them like this: useQuery([MyQuery]Document, { variables: { ... } })
          • Now, after checking that there is no error or loading, we can use the data
        • For mutation:
          • const [myMutation] = useMutation([MyMutation]Document);
          • Now the myMutation function can be called like this: myMutation({ variables: { ... } })
    • If you want to add/change a field on a backend database model:
      • Change the model class in the models.py file, in the appropriate feature folder under backend/apps
      • Generate a Django migration to update the database
        • cd into backend, and type python manage.py makemigrations (with your virtual environment activated!)
        • Update your local database with python manage.py migrate
          • If running the backend through Docker: type docker compose exec backend python manage.py migrate instead
    • If you want to add/change a field on a type in the GraphQL API:
      • Change the type class in the types.py file, in the appropriate feature folder under backend/apps
      • If it's a new field from the type's Django model:
        • Simply add the field name in the fields list on the type's Meta class
      • If it's a field that only exists on the API type, but not on the database model:
        • Add field_name = graphene.FieldType() under the class name, replacing field_name and FieldType with the appropriate name and type for your field
        • Add a method resolve_field_name with the @staticmethod decorator on the class, with the logic for how to get data for the field
      • Re-generate the backend's schema.json
        • cd into backend, and type python manage.py graphql_schema (with your virtual environment activated!)
    • If you want to add/change a query (to fetch data) or mutation (to change data) in the GraphQL API:
      • Find the query resolver method in resolvers.py, or the mutation class in mutations.py, in the appropriate feature folder under backend/apps
        • Examples:
          • The resolver for the allOrganizations query is the resolve_all_organizations method on the OrganizationResolvers class in backend/apps/organizations/resolvers.py
          • The createOrganization mutation corresponds to the CreateOrganization class in backend/apps/organizations/mutations.py, with an OrganizationInput class for its arguments, and a mutate method for the actual mutation logic
      • Add/change your query resolver method or mutation class
      • If you added a new query/mutation, update the schema.py file in the same folder to expose it through the API:
        • For a query: add a new field for the query in the ...Queries class, with the appropriate graphene type for what the query returns
        • For a mutation: import YourMutation class from .mutations, and add your_mutation = YourMutation.Field() to the ...Mutations class (obviously replacing your_mutation / YourMutation with the name of your mutation)
      • Re-generate the backend's schema.json
        • cd into backend, and type python manage.py graphql_schema (with your virtual environment activated!)
  • Commit your changes to Git
    • If your changes are large, consider splitting it up into different commits for different files
    • In the terminal:
      • Type git status to see which files you have changed
      • If you want to add them all, type git add . from indok-web
        • Otherwise, you can do git add followed by the path of the specific file you want to add
      • Type git commit -m "add example component for example feature"
        • Replace the message here with your own short, descriptive message describing the changes!
        • Git commit messages should be written in imperative, e.g. add rather than adds / added
    • In VSCode:
      • Go to the Source Control tab on the left
      • Click + on the files you want to add to the commit
      • Write a commit message in the text box, then click Commit
    • If it complains about missing black / flake8:
      • This is because we have configured "pre-commit hooks" to format and lint your code on commit
      • Since black and flake8 are part of your Python virtual environment, you have to activate your virtual environment for these to work
        • In the terminal, type source venv/bin/activate (Mac) / .\venv\scripts\activate (Windows) / venv (from Rubberdøk Slack)
        • If committing through the terminal, just run git commit again after this
        • If committing through VSCode, you may have to restart VSCode from the terminal to use your virtual environment (code .)
    • If you get errors from pre-commit hooks, look through the error message to see what you have to fix
  • Push your branch to GitHub
    • In the terminal:
      • Type git push -u origin add-example-feature, replacing add-example-feature with your branch name
    • In VSCode:
      • Go to the Source Control tab on the left
      • Click ... -> Push
        • If it asks if you want to publish your branch, click OK
  • Make a Pull Request on GitHub
    • Go to github.com/rubberdok/indok-web/branches
    • Click New Pull Request on your branch
    • Write a concise, but descriptive summary of your changes
    • Request a review from another developer
    • Respond to any questions or concerns they may have with your Pull Request
    • If an automatic test fails, click Details on it to see what went wrong in the logs
    • Once your Pull Request is approved, and the tests pass, you can merge it - now your changes are live!

Comprehenceive Api and Backend Models Guide

Making a model (changes to the database)

The models.py file is essentially a description of what should be stored in our database. Types.py tells graphene, the service we use to autogenerate a ton of stuff what types the database has.

If you are adding a brand new models.py file make sure to add your changes to LOCAL_APPS in the base.py of our django settings. In order to make the migrations work you will also need a migrations folder containing a file named init.py. The file init file is empty but nessecary.

After changes have been made to thease files you need to push them to the database. This is done first by making the migrations using docker compose exec backend python manage.py makemigrations After the migrations are made you migrate useing docker compose exec backend python manage.py migrate. For the changes to show up in the admin panel you will need to restart docker

Making a query

A query is a request for data made to the backend by the frontend. The following is a guide on how to make queries.

Queries in Backend

All queries have a respective resolver function in the backends resolvers.py function. This is how the backend knows what to send to the frontend. A resolver function is ALWAYS named resolver_something. Note that Python uses camel case and GraphQL does not. This means that in communication the frontend is going to capitalize the letter(s) after the underscore(s) and remove the underscore. For example, the resolver, resolve_get_winners_list, will be referenced as getWinnersList in the frontend.

All resolvers must also be referenced in the schema.py file. Here they are again named using camel case and given return types, often the type is just the model from models.py.

If you are making the first queries of this backend folder you will also need to add the schema to backend/config/schema.py. This is to tell the command python manage.py graphql_schema to include the new schema file that it exists.

After adding the new resolvers you can run docker compose exec backend python manage.py graphql_schema in the indok-web directory to add the new schema. The query is now done from the backend perspective. NOTE: if you have forgotten to add the resolver to the schema or done so incorrectly the terminal will say it was successful. After this command, there should be a change in schema.json.

Queries in Frontend

In the frontend all query defining is done in the graphql folder. The generated folder should not be touched! (However it can be useful to look at in troubleshooting).

The graphql folder usually has 3 files, mutations, queries and fragments. Fragemnts are selections of fields on one of our API types, that can be reused across different queries/mutations to ensure consistent types. You can read more here: (https://www.apollographql.com/docs/react/data/fragments/). If a selection is used only once it can be written in the queries file directy.

After having written your query run the command yarn generate in the frontend directory to generate machine readable queries.

After the above is done the queries can be used and tested. In code they are used using the apollo function useQuery. Here is an example: const { error, loading, data } = useQuery(GetWinnersListDocument);. Notice the three terms before the query. Things can ALWAYS go wrong with queries and they requre data to be sent, therefore it is common to define what is done in rare cases.

  • data is the normal data when the query has returned something expected from the backend.
  • loading is a waiting status. Queries are not instant and it can be useful to define some action while waiting.
  • error is what you recive if the query returned that something has gone wrong. This should almost always have some sort of notification to the user and or admins.

An important security notice: Permissions are handled in the backend. It is possible for anyone to try to call queries withut a frontend interface, it is therefore important that all queries that should have a permission check has them before it is pushed to production regardless of if there exists a frontend interface.

One last note about queries is that we limit size. If you return more than about 300 items the query will fail. Therefore it is important that sorting and things of that kind is done in the backend.

Making a mutation

A mutation is a request for data to be changed or added made to the backend by the frontend. The following is a guide on how to make mutations. Note that it is very similar to making a query.

Queries in Backend

All mutations have a respective mutation class in the backends mutations.py file. This is how the backend knows what to change when the mutation is called. A mutation class has no strict naming scheme but it is higly reccommended to end the name in "Mutation". Every mutation class has a function named mutate that does the changing, an Arguments class that takes in the data that can be passed from the frontend, and an ok that is returned if the mutation is successful.

All mutations must also be referenced in the schema.py file. Here they are named using camel case for the name of the mutation.

If you are making the first mutations of this backend folder you will also need to add the schema to backend/config/schema.py. This is to tell the command python manage.py graphql_schema to include the new schema file that it exists.

After adding the new resolvers you can run docker compose exec backend python manage.py graphql_schema in the indok-web directory to add the new schema. The mutation is now done from the backend perspective. NOTE: if you have forgotten to add the resolver to the schema or done so incorrectly the terminal will say it was successful. After this command, there should be a change in schema.json.

An important security notice: Permissions are handled in the backend. It is possible for anyone to try to call mutations withut a frontend interface, it is therefore important that all mutations that should have a permission check has it before it is pushed to production regardless of if there exists a frontend interface.

Mutations in Frontend

In the frontend all mutation defining is done in the graphql folder. The generated folder should not be touched! (However it can be useful to look at in troubleshooting).

The graphql folder usually has 3 files, mutations, queries and fragments. Obvously mutations are written in the mutations folder.

After having written your mutation run the command yarn generate in the frontend directory to generate machine readable mutation.

After the above is done the queries can be used and tested. In code they are used using the apollo function useUsemutation to define a function that can be run. Here is an example: const [logTicTacToe] = useMutation(LogTicTacToeDocument);. After this the logTicTacToe function can be used to run the mutation. It lookes like this: logTicTacToe({ variables: { winner: "Draw" } }); Note that this does not trigger a react rerender so if you need to change visuals you need to handle that as well.

An important security notice: Permissions are handled in the backend. It is possible for anyone to try to call queries withut a frontend interface, it is therefore important that all queries that should have a permission check has them before it is pushed to production regardless of if there exists a frontend interface. Most mutations (mabye all the ones we currenly have) need a permission check.

Tech Stack

Error logging

The project has error logging through Sentry, and can be accessed by logging in with GitHub.

Deployment

The app is deployed through AWS ECS.

Other Services

  • E2E testing through Cypress, publicly accessible.
  • Code coverage through Codecov, accessible with Github SSO.
  • Domains managed through domene.shop.
  • Postmark as e-mail service, contact an administrator for access.
  • Vipps, contact an administrator for access.
  • Feide, contact an administrator for access.
  • AWS for various services, contact an administrator for access.
  • Google Workspace for account management, contact an administrator for access.
  • Slack for communication, available with a rubberdok.no domain.

Contributing

This project is completely open source and is intended to serve as a platform for students who are interested in web development to have a project where they can find inspiration and contribute, and as such, we gladly welcome outside contributors to the project. If you're interested in how to get started, no matter what level of experience you have, please see CONTRIBUTING.

Feedback

Found a bug, got a suggestion, or something we should know about? Take a look at the roadmap and file an issue if it's not on the roadmap.

Acknowledgements

Logo created by mathiasraa

Powered by Vercel