forked from anitab-org/mentorship-backend
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: improve and add new documentation (anitab-org#683)
Co-authored-by: Gauri V. Nair <[email protected]>
- Loading branch information
1 parent
2f1b663
commit 8677375
Showing
6 changed files
with
225 additions
and
8 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| # CI / CD process | ||
|
|
||
| This document aims to explain everything related to Continuous Integration and Continuous Development (CI / CD) processes of the app. | ||
|
|
||
| ## Deployment process | ||
|
|
||
| This app is in current development under the `develop` branch. The `master` branch is currently empty, because we have not yet put this into production (however this is in the works). | ||
|
|
||
| Currently, we have the development version of this app deployed on [Heroku]. Because we have "Automatic Deploys" feature enabled, every time a new pull request is merged into `develop` branch a new version of the app is deployed to [Heroku]. | ||
|
|
||
| 🔗 https://mentorship-backend-temp.herokuapp.com/ | ||
|
|
||
| ## Pull Request Checks | ||
|
|
||
| We use [GitHub Actions](https://github.com/features/actions) to perform checks on every PR which runs unit tests and performs code coverage analysis. | ||
| You can see the GitHub actions workflow [here](/.github/workflows/main.yml). | ||
|
|
||
| We use [Codecov](https://codecov.io/) to check the code coverage in our code. | ||
|
|
||
| ## Development environment | ||
|
|
||
| As mentioned before in the development environment we are hosting the app on [Heroku] so that it is available to anyone interested in testing it without having to set up the development environment locally. | ||
|
|
||
| Regarding the data we host, we are using a PostgreSQL database as a service called [ElephantSQL], to which the Heroku app is connected. | ||
|
|
||
| [Heroku]: https://www.heroku.com/ | ||
| [ElephantSQL]: https://www.elephantsql.com/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| This page explains how the project is structured. | ||
|
|
||
| ## Basic Architecture | ||
|
|
||
| <p align="center"> | ||
| <img alt="basic architecture" src="https://user-images.githubusercontent.com/11148726/44174311-ac5eaa80-a0da-11e8-92bb-ca2fe7c26f60.png"> | ||
| </p> | ||
|
|
||
| **Main Components:** | ||
| - **Data Model:** This contains all database models, which are implemented using SQLAlchemy Model abstraction, e.g.: UserModel, MentorshipRelationModel. | ||
| - **Data Access Object (DAO):** These classes contain functions used by the API resources and use Database Models. | ||
| - **API Resources:** This is responsible for the REST API available form the deployed server. These resources define the namespaces, i.e., resources HTTP methods. It's also responsible for Swagger documentation. | ||
|
|
||
| ### Root project structure | ||
|
|
||
| | Folders and files | Description | | ||
| |-------------------|---------------------------------------------------------------------------------------------------------| | ||
| | .github | Contains files related to GitHub (e.g.: pull request and issue templates, contributing guidelines, ...) | | ||
| | app | Contains most of the development code | | ||
| | docs | Contains non-production code (e.g.: Swagger and Postman template to test API) | | ||
| | templates | Contains html templates used by the app (e.g.: verification email template) | | ||
| | tests | Contains all unit tests | | ||
| | config.py | Has the different set of configurations the app can run with | | ||
| | run.py | Main entry point of the app | | ||
| | requirements.txt | Describes all dependencies of the app | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| These are some of the standards we choose to follow in this project. These might change if we agree on standards for python development within the community. | ||
|
|
||
| ### Docstrings | ||
|
|
||
| We follow the Comments and Docstrings guidelines from [this style guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings). | ||
|
|
||
| ### Type Hints | ||
|
|
||
| We use [type hints (PEP 484)](https://www.python.org/dev/peps/pep-0484/) which came with Python 3.5 to ease development experience and understand the function's signature better. For reference, this started with [PR #354](https://github.com/anitab-org/mentorship-backend/pull/354). | ||
|
|
||
| ### String interpolation | ||
|
|
||
| We use f-strings as referred in [PEP 498 -- Literal String Interpolation](https://www.python.org/dev/peps/pep-0498/). | ||
|
|
||
| Example: | ||
| ```python | ||
| my_name = "Jane Doe" | ||
| greetings = f"My name is {my_name}!" | ||
| ``` | ||
|
|
||
| ### HTTP Status codes | ||
|
|
||
| Instead of using HTTP status codes hardcoded in literal format, we use [HTTPStatus module](https://docs.python.org/3/library/http.html) codes. | ||
|
|
||
| Example: | ||
| ```python | ||
| from http import HTTPStatus | ||
|
|
||
| def ok_status_code: | ||
| return HTTPStatus.OK #200 | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| # Features Overview | ||
|
|
||
| This backend has many features that allow for members of Mentorship System to establish mentorship relations with each other for a certain period of time. | ||
|
|
||
| **High level capabilities:** | ||
|
|
||
| - A member in the system can see other members and choose someone to send a mentorship request to. | ||
| - Members can accept, reject mentorship requests and cancel an ongoing mentorship relation. | ||
| - Members can wrtie their own profiles and make themselves available to mentor or be mentored. | ||
|
|
||
| ## Cron jobs | ||
|
|
||
| Cron jobs or schedulers are tasks that run from time to time. We have some that aare important for the functionality of the app. | ||
|
|
||
| 1. Delete unverified users every month. Code can be found [here](/app/schedulers/delete_unverified_users_cron_job.py). | ||
|
|
||
| We have this because we don't want to keep users in our database if they are inactive and have not verified their email. | ||
|
|
||
| 2. Complete mentorship relations every day. Code can be found [here](/app/schedulers/complete_mentorship_cron_job.py). | ||
|
|
||
| Every day we run a job that completes mentorship relations which reached the end date agreed upon by mentor and mentee. | ||
|
|
||
| ## Main concepts | ||
|
|
||
| These are the main base concepts of the application: | ||
|
|
||
| - **User:** User represents a person that is registered in the application. This has the capability to log in into the Mentorship System. The User can have two roles in the system: mentor or mentee. The user can also be in the app and not assume any of these rules. | ||
|
|
||
| - **Mentorship Relation:** A mentorship relation represents a relation between a mentor and a mentee, i.e., two users of the system. It has a time limit, i.e., it can only last for a certain period of time agreed upon by both parties. They can have data shared which are viewed only by them. This data includes tasks, meetings, notes from the agreement between the two users. It also holds information that represents a mentorship agreement between both the mentor and mentee, containing a description of the relation, end date and indication of who assumes the role of mentor and mentee. Learn more about [how it is implemented here](Mentorship-Relation-Documentation). | ||
|
|
||
| - **Task:** A task is an assignment that both the mentor and the mentee can create related to a Mentorship Relation. This tasks can be completed, and only then they become achievements of the relation. | ||
|
|
||
| _**Note:** This next concept was a part of the initial proposal, not yet implemented._ | ||
|
|
||
| - **Meeting:** A meeting is an event agreed by mentor and mentee. Any of the users can create it, although they have to agree on it for the meeting to happen. This meeting as a date and time, and optionally a place. The meeting can have some notes attached. | ||
|
|
||
| ### Mentorship Relation | ||
|
|
||
| A **Mentorship Relation** is when two Users, a mentor, and a mentee are matched together to mentor and support each other. This is a 1 to 1 relation, involving just 2 users, during a certain period of time. | ||
|
|
||
| A **Mentorship Relation request** is when a User sends a sort of contract in which the other User has to accept so that a mentorship relation can start. This contract contains notes/description, the definition of who will be the mentor and the mentee and the end date of the relation. Currently, this contract cannot be edited after sent by the User. | ||
|
|
||
| #### Conceptual Implementation | ||
|
|
||
| Considering two users, _User 1_ and _User 2_. Let's say _User 1_ sends a mentorship request to _User 2_ (next image illustrates this). | ||
|
|
||
| <p align="center"> | ||
| <img alt="User 1 sends a mentorship relation request to User 2" src="https://user-images.githubusercontent.com/11148726/43965132-68650400-9cb6-11e8-8667-92a181823845.png"> | ||
| </p> | ||
|
|
||
| Looking at the next image, you can consider these 3 stages: | ||
| - (1): Before a request is sent | ||
| - (2): When the User receives a request | ||
| - (3): After a relation starts | ||
|
|
||
| #### Relation states and stages | ||
|
|
||
| <p align="center"> | ||
| <img alt="Stages and states of a Mentorship Relation" src="https://user-images.githubusercontent.com/11148726/43964310-73dd99ac-9cb4-11e8-8353-96abadc53ce1.png"> | ||
| </p> | ||
|
|
||
| The next table explains more of the image above. | ||
|
|
||
| | State | Who can trigger this | How is this triggered | Constraints | | ||
| |-----------|--------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------| | ||
| | PENDING | Any User (E.g.: User 1 and User 2) | A User sends/creates a mentorship relation request using the frontend application or backend API | N/A | | ||
| | ACCEPTED | The User that received the request (E.g.: User 2) | The User that received the request can accept this using the frontend application or backend API | Sets only if the relation is in the PENDING state | | ||
| | REJECTED | The User that received the request (E.g.: User 2) | The User that received the request can reject this using the frontend application or backend API | Sets only if the relation is in the PENDING state | | ||
| | CANCELLED | Both Users participation in a current relation (E.g.: User 1 and User 2) | Any of the 2 Users participating in the relation can cancel the current relation both on the frontend application or backend API | Sets only if the relation is in the ACCEPTED state | | ||
| | COMPLETED | A cron job running every day 23h59 (automatically) | A cron job in the backend iterates over every mentorship relation, in the ACCEPTED state, and sets this states for relations that passed the end date | Sets only if the relation is in the ACCEPTED state | | ||
|
|
||
| **Note:** Even though is not represented in the previous image, the User that sent the mentorship request can delete the request if its state wasn't changed by the receiving User. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| ## How it works | ||
|
|
||
| User Authentication is [JSON Web Token (JWT)](https://jwt.io) based. To implement this we use a flask extension, flask-jwt-extended. You can see an example of [basic usage with this extension here](https://flask-jwt-extended.readthedocs.io/en/latest/basic_usage.html). | ||
|
|
||
| In short, when a user logs in (`POST /login`), the user will receive an authentication token (e.g.: `access_token`) which contains part of the user's identity and other token related fields, as the expiration date. Expriry date comes as a [UNIX timestamp](https://www.unixtimestamp.com/) in the `access_expiry` attribute in the response. | ||
|
|
||
| You can get an access token once you are registered into the backend. Here's a quick tutorial on [how to login using Swagger UI](https://github.com/systers/mentorship-backend/wiki/Log-in-using-Swagger-UI) provided by the deployed server. | ||
|
|
||
| The user can then use this `access_token` when using a protected/restricted API, such as, `GET /user` API. To access this the client has to send the `access_token` in the header of the HTTP request, following this format: "Autorization: Bearer `access_token`". | ||
|
|
||
| ## Example | ||
|
|
||
| Here's an inside look at an `access_token` using [jwt.io](https://jwt.io) Debugger. | ||
|
|
||
|  |