Merge pull request #116 from SELab-2/development

Merge development into main for the release

README.md

@@ -29,3 +29,42 @@ After this is done and the branch is finished, a pull request from this branch t
 ## Documentation
 
 The documentation for both the backend and frontend are automatically generated based on the comments in the files. The docs of the backend and frontend are seperated, so you will need to build them independently. For generating and reading them, see the README.md files in `backend/docs` and `frontend/docs`.
+
+# Development
+
+## Entire stack
+
+To start the development environment, run
+
+```shell
+./dev.sh full
+```
+
+The frontend will be available at [http://localhost/](http://localhost/), the api at [http://localhost/api/](http://localhost/api/), and the docs at [http://localhost/docs/](http://localhost/docs/).
+
+Services can also be reached directly via the ports specified here:
+
+| Service  | Port |
+|----------|------|
+| Frontend | 8000 |
+| Backend  | 8001 |
+| Docs     | 8002 |
+| Postgres | 5432 |
+
+## Individual services
+
+To just run frontend, backend, or docs, run
+```shell
+./dev.sh {frontend|backend|docs}
+```
+
+## Rebuilding image
+To rebuild a docker image, add `--build`. This is necessary in some cases, for example when the dependencies changed. Docs will also only be updated when rebuilding the image.
+
+# Testing
+
+Run 
+```shell
+./test.sh {frontend|backend}
+```
+to run the tests in docker. Optionally add `--build` to rebuild the image if needed.

backend/README.md

@@ -37,3 +37,21 @@ python manage.py makemigrations drtrottoir
 This will create a new migration in the migrations folder. These migrations
 should then be committed to Git. To apply these migrations, run `python
 manage.py migrate`.
+
+## Generating mock data
+
+An admin command is provided to populate the database with some mock data for
+testing:
+
+```sh
+python manage.py mockdata [password]
+```
+
+Here, the `password` argument is used to create a student, superstudent, admin
+and syndicus with the given password (with emails `[email protected]`,
+...), which can then be used to log into the system. For public test
+deployments, make sure this is a **good password**.
+
+This script does not support being ran multiple times. If you wish to reset the
+database, use `python manage.py flush` first, and then re-run the above
+command.

backend/docs/docs/overview.rst

@@ -0,0 +1,95 @@
+========
+Overview
+========
+
+Dr. Trottoir is a service company that manages trash cleanup schedules for apartments and similar
+housing buildings. To do so, Dr. Trottoir hires students to enter these buildings on assigned dates who
+take out the necessary trash. Because multiple buildings can share the same trash cleanup schedule, these
+buildings will be grouped in a route. A student who is out to perform his work will visit all buildings in
+a route and take out the trash for each of these buildings. To achieve a higher efficiency, the order of
+visits in these routes are determined beforehand.
+
+While a student is out on a route, a supervisor, called a super student, will be able to track which
+buildings have been visited. Super students will also have administrator rights to add, remove or
+manage routes, student schedules, and student permissions. A building owner (syndicus) will be
+given an account, which can also be added or removed by super students.
+
+In order for super students to verify the students are actually doing their work, students will have to take
+pictures with their phones and upload them to the database. At least one photo must be taken for arriving
+at a building, for taking out the trash, and for leaving the building, per building. If a student encounters
+any troubles at a building they can create an issue to report this to the super students, which will notify the
+building's syndicus.
+
+User
+****
+
+A user represents a user account from the django framework. Asides from the user model, there are
+also user roles. These roles are: student, super student, admin and syndicus. Theoretically a user can
+have multiple roles, although in practice it is expected for a user to only have one. The user role
+determines the permissions of the actions the user can take, according to the endpoint specifications.
+
+Location Group
+**************
+
+A location group is a grouping of objects, such as users or buildings, by a location. Concretely, these
+will be cities, such as Ghent or Antwerp. Location groups are useful for separating permissions in
+different locations: a super student from Ghent does not need to know the schedule assignments of a
+student in Leuven for example.
+
+Building
+********
+
+A building represents a physical building that students can visit. Buildings are limited to a location
+group and contain an address and pdf guide. This guide can be used by students to navigate around the
+building, if needed.
+
+Garbage Type
+************
+
+A garbage type is a type of garbage that can be cleaned up, such as plastic or cardboard.
+
+Garbage Collection Schedule
+***************************
+
+A garbage collection schedule is a description of a type of garbage needs to be taken
+out in a building on what day. For example, a garbage collection schedule entry can say that
+on March 1st 2024 in building X the plastic will need to be taken out. Because buildings
+will commonly only have a specific set of garbage types, a combination of building and garbage
+type can be templated, to speed up the creation of future garbage collection schedules.
+
+Schedule Definition
+*******************
+
+A schedule definition describes a route containing the buildings a user must visit in one night. A
+schedule definition is limited to a location group and contains the name of the route. The list of
+buildings is stored in the ScheduleDefinitionBuilding model, which also contains the order in which
+the building must be visited in a route.
+
+Schedule Assignment
+*******************
+
+A schedule assignment is the assignment of a route (schedule definition) on a specific day to a specific
+student. This model is the main component for handling student schedules.
+
+Schedule Work Entry
+*******************
+
+A schedule work entry contains an image a student has taken to prove they have done a certain task in their
+route, such as leaving a building they have finished. It also contains which user has taken the picture,
+at what time they have taken the picture, and where (at what building) they have taken the picture.
+
+Issue
+*****
+
+An issue is any sort of comment a student can make on a building during their route. Super students can
+verify if this is an actual issue and notify the syndicus if needed. If a syndicus has received an issue
+and have solved it, they can mark the issue as resolved. Students are able to add one or more images to
+their issues.
+
+Additional info
+***************
+A full overview of the endpoint descriptions can be found on the drive storage.
+
+Below is a graphical overview of the used tables.
+
+.. image:: ../images/domainmodel.png

backend/docs/docs/views.rst

@@ -3,70 +3,70 @@ Views
 =====
 
 ``Building``
-########
+############
 
 .. automodule:: drtrottoir.views.building
    :members:
 
 
 ``Garbage collection schedule``
-###########################
+###############################
 
 .. automodule:: drtrottoir.views.garbage_collection_schedule
    :members:
 
 
 ``Garbage collection schedule template``
-####################################
+########################################
 
 .. automodule:: drtrottoir.views.garbage_collection_schedule_template
    :members:
 
 
 ``Garbage type``
-############
+################
 
 .. automodule:: drtrottoir.views.garbage_type
    :members:
 
 
 ``Issue``
-#####
+#########
 
 .. automodule:: drtrottoir.views.issue
    :members:
 
 
 ``Issue image``
-###########
+###############
 
 .. automodule:: drtrottoir.views.issue_image
    :members:
 
 
 ``Location group``
-##############
+##################
 
 .. automodule:: drtrottoir.views.location_group
    :members:
 
 
 ``Schedule assignment``
-###################
+#######################
 
 .. automodule:: drtrottoir.views.schedule_assignment_views
    :members:
 
 
 ``Schedule definition``
-###################
+#######################
 
 .. automodule:: drtrottoir.views.schedule_definition
    :members:
 
 
 ``Schedule work entry``
-###################
+#######################
 
 .. automodule:: drtrottoir.views.schedule_work_entry_views
    :members:

backend/docs/index.rst

@@ -1,12 +1,15 @@
 Welcome to Dr Trottoir's documentation!
 =======================================
 
-This is the main page of the Dr Trottoir backend documentation. For more information on building and editing the documentation, see the README.md file.
+This is the main page of the Dr Trottoir backend documentation. For more information on building and
+editing the documentation, see the README.md file. A high level overview of the backend architecture
+can be found in the overview section. The backend is built using django and django-rest-framework.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   docs/overview
    docs/views
    docs/models