From f4dc51e69931460ddebd957ef5a538de71173402 Mon Sep 17 00:00:00 2001 From: iggy <i.kepka@student.utwente.nl> Date: Wed, 21 Feb 2024 20:14:43 +0100 Subject: [PATCH] Finished README.md. Will start with adding comments to crucial components of the backend/API. --- README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 77 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 29d3518..81a087f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,30 @@ # MySU is a member administration tool used to provide a common platform for any association willing to be a part of it. -### Backend of MySU is divided into several components: +## This document provides comprehensive information about: +- The **purpose** and **final goal** of the application. +- **Description** of each **component** and **subcomponent** of the project. +- **Guide** for **backend** setup. +- **Guide** for **frontend** setup. +- **Structure** of the **backend** repository. +- **Structure** of the **frontend** repository. +- **URLs** of: **local**, **development** and **live** versions of the backend/API and frontend. +- **Tips** for the future administrator. +- **URLs** to both **frontend** and **backend** gitlab repositories. + +### Its primary purpose is to provide starting or existing small and medium size associations a tool to manage their associations. +- **Board members** can manage all members of the associations. +- **Board members** can create events, in which the members of the association can participate in. +- **Board members** can manage the finances of different members within the association. +- **Application** can be setup by board members to send emails with arbitrary content to the members of the association. + +### Its secondary purpose is to allow associations to interact with each other, creating a network of associations. +Events can be set to be seen by other associations, allowing members of different associations to join the same event. + +### Its final goal is to create a universal web platform for all small and medium size associations. +With several associations joining the platform, it would allow to create a network of associations. +This could prove beneficial in the future e.g., UT hosting a big event involving multiple associations + +# Backend of MySU is divided into several components: - **Buddy** is responsible for matching different users of the app. Currently, the application is in no way linked to the frontend, but is required for it to run. - **Calendar** is responsible for handling events provided by different associations. It contains information about: enrollment, enrollment options, event types, and events themselves. - **Email** is responsible for distributing emails to members of the various associations. @@ -9,13 +33,59 @@ - **Backend [MySU]** is a main part of the code that the other components are built upon. It handles all the major work and provides the functionality for the web application. - **Exams** and **Inventory** are **deprecated** and have no use for the main App, as of now. Can be found in "Unused Apps" directory. -## In order to properly setup the backend/API of MySU application in local environment, follow: +# It is assumed that: +- The current administrator is acquainted with the basics of Django, Django-API and other related frameworks (Backend/API). +- The current administrator is acquainted with the basics of Node.js (Frontend). +- The current administrator is well acquainted with the Python language. +- The current administrator is well acquainted with the SQL language. + +# In order to properly setup the backend/API of MySU application in local environment, follow: - https://gitlab.utwente.nl/my-su/backend/api/-/wikis/home - https://gitlab.utwente.nl/my-su/backend/api/-/wikis/Local-Installation +- The installation is successful, if after running the project you can access the locally run API on URL: +**http://127.0.0.1:8000/** +- Note that the local backend comes with pre-made "fixtures" that populate the djangoDB with dummy data. + +# In order to properly setup the frontend, and link it locally with the backend and API of the applications: +- clone the gitlab repository of the frontend (link can be found at the bottom of the document) +- in the IDE move to the website folder +- open the terminal and run the command (it may take a while): +```zsh +npm install +``` +- next open the .env file and add the line: +```node +REACT_APP_API_URL='http://127.0.0.1:8000/' +``` +- comment out the line: +```node +REACT_APP_API_URL='https://dev.sun.snt.utwente.nl' +``` +- lastly run this command in the terminal: +```zsh +npm start +``` +After the application is started, you can open your browser and head to URL: +### **https://localhost:3000** + +**Note that the local frontend of MySU will only run properly, if the backend/API is already setup and running locally.** + +## Gitlab repository of the backend contains two main branches: +- **main branch**: this is the production code that is run on: +**https://api.sun.utwente.nl/** +- **development branch**: this is the development code that is run on: +**https://dev.sun.snt.utwente.nl/** +- Any changes made to the application, should be done on separate branches. + +## Gitlab repository of the frontend contains one branch: +- **website branch**: this is the code that is run both by the production and development version. +- **production:** **https://my.su.utwente.nl/** +- **development:** **https://sun.snt.utwente.nl/** +- It is also the same version run **locally**. -## It is assumed that: -- The current administrator is acquainted with the basics of Django, Django-API frameworks (Backend/API) -- The current administrator is acquainted with the basics of Node.js (Frontend) +## In reality, there are two directories that are going to be administered by the future administrator: +- **api/apps/MySU** - responsible for handling the API requests and responses +- **api/MySU** - responsible for handling the backend (logic and functionality) -## [More information about the Backend can be found here.](https://gitlab.utwente.nl/my-su/backend/api) -## [More information about the Frontend can be found here.](https://gitlab.utwente.nl/my-su/frontend/website) \ No newline at end of file +### [More information about the Backend can be found in this repository.](https://gitlab.utwente.nl/my-su/backend/api) +### [More information about the Frontend can be found in this repository.](https://gitlab.utwente.nl/my-su/frontend/website) \ No newline at end of file -- GitLab