database relationship and authorizations

docs/db/db-authorization.md

@@ -0,0 +1,61 @@
+# DB authorization
+
+Every request to Hasura executes against a set of session variables. These variables are expected to be set by the authentication system.
+
+Normally there are some main variables for the authorization context:
+
+- `X-Hasura-User-Id`: this variable usually denotes the user executing the request.
+
+- `X-Hasura-Role`: This variable denotes the role with which the user is executing the current request. Hasura has a built-in notion of a role, and will explicitly look for this variable to infer the role.
+
+- `X-Hasura-campus`: this variable contains the campus that the user currently is on.
+
+In our database we have several roles which are simple arbitrary names.
+Each role can be given a set of permissions and actions (`select`, `insert`, `update`, `delete`). That will execute against each table of the database.
+
+To give the user with a certain role a permission to make a request, we must set a permission rule that would look something like this:
+
+```json
+{"user_id": {"_eq": "X-Hasura-User-Id"}}
+```
+
+This is the same as saying : if the value of the `user_id` column equals the value of the session variable `X-Hasura-User-Id`, allow this request to execute on the current row.
+
+It is possible to express pretty complex rules, by using, for example the operators `_and` and `_or` to create a chain rule. It is even possible to query tables not related to the current object as part of the rule execution. You can see more about it [here](https://hasura.io/docs/latest/graphql/core/auth/authorization/index.html).
+
+## Roles
+
+These are the roles presented in the database:
+
+- `anonymous`: this role allows non logged in users to query (only using `select`) tables:
+  - `users` : and columns `id`, `login`
+  - `object` : and columns `id`, `childAttr`, `campus`, `name`, `type`
+  - `result` : and columns `groupId`, `objectId`, `progressId`, `userId`, `grade`, `campus`
+  - `transactions` : and columns `objectId`, `userId`, `amount`, `type`
+  - `progress` : and columns `isDone`, `objectId`, `userId`, `id`, `grade`, `campus`
+
+- `user` : this role allows the following queries:
+
+  - without check:
+    - `group`, `group_user`, `match`, `registration_user`, `event`, `event_user`, `object`, `object_child`, `object_status`, `object_type`, `registration`, `role`, `transaction_type`
+
+  - with checks:
+    - `audit`, `result`, `transaction`, `user_role`, `user`, `progress`
+
+- `campus-admin` : this role allows users to query every table, but with the session variables `X-Hasura-campus` check. This means that users with this role will only be able to query information from their own campus.
+
+- `admin-campus-read-only` : this role allows users to query almost all tables with a campus permission verification.
+
+Example:
+
+```json
+{ "campus" : { "_in" : "X-Hasura-campus" } }
+```
+
+- `admin` : this role allows users to query any action in any table on the database.
+
+- `admin-read-only` : this role allows users to query almost all tables only using the `select` action.
+
+This is how the user and role tables are related to each other:
+
+![alt text](../img/db/user-roles.jpg "hierarchical roles")

docs/db/db-relations.md

@@ -0,0 +1,184 @@
+# Database Relations
+
+## Entity Relationship Diagram ERD
+
+An entity relationship diagram (ERD) shows the relationships of entity and sets stored in a database.
+
+An entity in this context is a table, this table contains a set of attributes, they can be of any data structure (INT, TEXT, ...).
+
+An entity can have several relations to other entities. Those relations are represented with "crow foots"
+
+### Relationships cardinality
+
+Relationships have a cardinality, normally they have two indicators that are shown on both sides of this line.
+
+1. The first line, refers to the **max** number of times that an instance of one entity can be associated with instances in the related entity. It can be **one** or **many** or **none**
+
+2. The second, describes the **min** number of times one instance can be related to others.
+It can be **zero** or **mandatory**
+
+The combination of those two indicators create relations, you can get more information [here](https://community.mis.temple.edu/mis3506digitaldesignfall2018/files/2018/10/Adam-Alalouf_Cardinality.pdf)
+
+![alt text](../img/db/db-relations.jpg "hierarchical roles")
+
+## Relations
+
+### Events
+
+Events will be the accumulation of the following tables :
+
+- `event`
+- `registration`
+- `registration_user`
+- `event_user`
+
+This part of the database takes care of schools activities with time.
+
+The `event` table contains the following relations:
+
+- `parentId` that is associated to himself. This association can be better explained if we take a look at the `path` column. An event can be based on a parent event (ex: the event `/madere/div-01/piscine-rust` is associated to this parent event `/madere/div-01`).
+
+- `registrationId` that is associated to the `registration` table. An event can have multiple registrations, but a registration can only be associated to one event, this being the parent event of the registration table.
+
+- `objectId` that is associated to the `object` table, this column will identify which object is associated to which event. An event can have multiple objects but must have at least one.
+
+---
+
+The `event_user` contains the associations between event and users. This will contain information on which users are registered to which event. An event can have multiple users and a user can have multiple events, this way being a many to many relationship.
+
+This table also contains an association to the **group** table. Users can or cannot have groups, the concept is the same as in `userId` but groups can be none.
+
+---
+
+The `registration` table contains all objects/activities that need registration. Having the following relations:
+
+- `parentId` that is associated to himself. As said above (in the events), it has the same use.
+- `objectId` that is associated to the object table, this is the object reference to the registrations.
+
+---
+
+The `registration_user` table is a relationship many to many between `registration` and `user`. This table contains all users that are registered to an event.
+
+- `registrationId` a registration can have multiple users.
+- `userId` a user can have multiple registrations.
+
+---
+
+### Objects
+
+Object will be the accumulation of the following tables :
+
+- `object`
+- `object_child`
+- `object_status`
+- `object_type`
+
+This part of the database defines the structure of the content.
+
+The `object` table contains the following relations:
+
+- `referenceId` that is associated to himself, an object can have none or many references. This attribute allows the creation of duplicates and permits each campus to create their own objects.
+- `authorId` that is associated to the user table and this is the author of that object/content.
+
+---
+
+The `object_child` table contains the encapsulation of objects, an object can have multiple children and a child must have one object parent. This table contains the following relationships to the object table:
+
+- `parentId` that associates the parent object to the child object.
+- `childId` that belongs to the parent object.
+
+Both child and parent must have at least one association to the `object` table, and the `object` table can have multiple relations with the `object_child` table.
+
+example:
+
+Campus `madeira` is a **parent object** of `piscine-go`, therefore the latter is the **child**.
+
+But `piscine-go` can be the **parent object** of all the quest, exams and raids (those being the **child objects**). And so on... creating a cycle.
+
+---
+
+### Users
+
+Users will be the accumulation of the following tables:
+
+- `role`
+- `user_role`
+- `user`
+- `group`
+- `group_user`
+- `token`
+- `record`
+- `transaction`
+
+---
+
+The `role` table contains permission roles for each user.
+
+---
+
+The `user_role` contains information on which users are associated to which role. A user can have multiple roles and a role can have multiple users.
+
+---
+
+The `group` table is the link between projects/objects and a group of users. This table contains the following relations:
+
+- `eventId` that associates which group is related to which event.
+- `captainId` that associates the captain's user.
+- `objectId` that associates which group is related to which object.
+
+---
+
+The `group_user` table contains the relation between groups and users. A group can have several users and so do the users, which can contain multiple groups.
+
+---
+
+The `token` table stores the tokens id from the hasura authorization variables for each user. This table as no relation between other tables.
+
+---
+
+The `record` table takes care of students records for example: bans. All relations in this table are with the table user.
+
+---
+
+The `transaction` table takes care of rewarding the user, by accumulating the user's **xp**. This table contains the following relations:
+
+- `userId` that represents the user rewarded
+- `eventId` that associates the event in which the user that was rewarded. Example: the user can be rewarded for an exercise `/madere/piscine-go/quest-01/make-it-better` and the parent event of that exercise will be `/madere/piscine-go`.
+- `objectId` that associates the object in which the user was rewarded. Example: if a user passes an exercise (object), the reward will be associated to that object.
+
+---
+
+#### Results
+
+Results will be the accumulation of the following tables:
+
+- `audit`
+- `match`
+- `progress`
+- `result`
+
+This part of the database defines the users/students progress in the school.
+
+The `audit` table contains all information related to the audit system and it is one of the ways of obtaining results. This table contains the following relations:
+
+- `groupId` that associates the group being audited.
+- `auditorId` as the name says, it is linked to the user table and has a relation of many to one. This column will be the auditor.
+- `resultId` that associates the audit to the result. An audit can have one or no results (depending on the auditor review). While, the results must have at least one audit.
+
+---
+
+The `match` table is another way of obtaining a result. This table is used in bonus exercises to match two users/students. The following relations are established:
+
+- `userId` this will be the user wanting the match to happen.
+- `matchId` this is a self related id, a match can be made by matching other students or it can be none. If the latter is none it means that the student is waiting for the match, otherwise it is a match.
+- `eventId` that associates the event to the current match. Example: a user can be waiting for the exercise `/madere/piscine-go/quest-01/teacher` that is located in the `/madere/piscine-go` event.
+- `objectId` that associates the object to the current match, this being the bonus exercise that the user is doing.
+
+---
+
+The `progress` table is the summary of multiple results. As the names says this is the students progress. The following relations are established:
+
+- `userId` that associates a user with a progress. A progress must always have a user associate to it and a user can or cannot have multiple progresses.
+- `groupId` this association allows groups to have progress. This is a many to none or one connection, meaning that a progress can have none or one group and a group can have multiple progresses.
+- `eventId` that associates which event the user has progressed on.
+- `objectId` that associates which object the user has progressed on.