Merge branch 'documentation' into 'master'

# Which JavaScript files does Portal need to run?

The important JavaScript files can be found in `/portal/static/js/`!

This is mostly Mithril.js.

## `/portal/static/js/components`

[TODO] furtherly explain the components

This is where the frontend components are located. The components are divided into two categories: `pages` and `pieces`. **Mithril.js** uses `pages` to render the main content of the website, while `pieces` are used to render smaller components that are used in multiple places. `pieces` then are embedded into `pages`.

This could help you around

+ [Mithril.js documentation](https://mithril.js.org/)

+ [Convert plain HTML to Mithril](https://arthurclemens.github.io/mithril-template-converter/index.html)

### `/portal/static/js/components/pages`

Generally, everything having its own tab in the Navbar is a `page`. They are the first components that are rendered when the website is loaded.

+ `Base.mjs`

+ `Fachschaftssitzung.mjs`

+ `FsServices.mjs`

+ `Login.mjs`

+ `M.mjs`

+ `Start.mjs`

+ `UniServices.mjs`

+ `Unlock.mjs`

### `/portal/static/js/components/pieces`

These are the smaller components that are embedded in multiple places.

+ `AccountRequired.mjs`

+ `Agenda.mjs`

+ `BoxedButton.mjs`

+ `ButtonAndTextLink.mjs`

+ `Nav.mjs`

+ `NavPageLink.mjs`

+ `PasswordinVault.mjs`

+ `ServiceLink.mjs`

+ `Toast.mjs`

+ `UnlockRequired`

## `/portal/static/js/model`

### `/portal/static/js/model/Service.mjs`

This renders an individual service.

### `/portal/static/js/model/Services.mjs`

This renders the list of our services.

## `/portal/static/js/account.mjs`

Here, after the login, a session token is created and stored in the `LocalStorage`.

It also responsible for ensuring the validity and non-expiry of the session token.

Users get logged in and logged out here.

## `/portal/static/js/gitlab.mjs`

Arcane magic. We get our Fachschaftssitzung protocols here.

Also, there's some yapping about the Same Origin Policy, might be interesting, but misses a TL;DR.

## `/portal/static/js/portal.mjs`

This is the main file that initializes the Mithril.js app and sets up the routing.

# Development

## Setup

### with docker

To run a flask shell inside the container:

```sh

sudo docker exec -it portal-app-1 flask shell

```

### without docker

```bash

# mkdir yourself into the portal directory

python3 -m venv venv

source venv/bin/activate

pip install -r requirements.txt

export FLASK_APP=portal

alembic upgrade head # to create (and update!) the database

flask run

```

---

#### Wichtig:

Alembic must always be up to date in order to update the database schema.

Please run `alembic upgrade head` after pulling changes from the repository.

---

## How to move around in this repo

## `/portal/`: Main Application

Here are all the important tech-stack related stuff and some Python files for Flask, contained in a cozy space

### `/portal/api/`: API Endpoints (Python)

Here you can find the API endpoints, written in Python

### `/portal/model`: database models (Python)

We use `SQLAlchemy` to interact with the database. The models are defined in this folder.

### `/portal/static`: CSS, JS, images, API documentation

This is giving the frontend some love and, more importantly, its purpose and functionality. The API documentation is also laying around here.

#### `/portal/static/css` (CSS, obviously)

Here you can find the CSS files for the frontend. The main CSS file is `main.css`.

#### `/portal/static/docs`

Here you can find the documentation for the API in its respective versions.

API specifications (`openapi-spec.yaml`) are written in OpenAPI 3.0.0 and are located in the `/api/{version}` folder.

#### `/portal/static/img`: Frag nicht, was für Bilder. Einfach Bilder. I won't translate this.

What did you expect?

#### `/portal/static/js`: JavaScript files

Lol, that should actually ![have its own README](JS-README.md).

It contains all the JavaScript files that are responsible for the frontend interactions.

### `/portal/templates`

These are the HTML files that Flask renders. They are written in Jinja2, which is a template engine for Python.

### `.py`-files

+ `__init__.py`: Fortunately, explaining this was not a Prog2 exam question

+ `db_config.py`: [TODO] Have fun, Jakob. Database configuration (arcane magic).

+ `main.py`: The Flask server is in here

+ `problem_details.py`: RFC 7807-compliant problem details responses for the API.