Refine README.md

README.md

 [![fsco.li/portal](./banner.png)](https://portal.fachschaft.cl.uni-heidelberg.de)
 
-# Development
+# Portal: this service can fit so many services in it!
 
-## Setup
 
-### with docker
+Aren't you tired of having to remember shortlinks or URLs for all the services offered by the Fachschaft? Does it embarrass you to always ask about the agenda of a Fachschaftssitzung, because you never worked with a Taiga implementation? How was the shortlink to Sturacloud again? Are you overwhelmed by 19 (and counting, **fast**) different services offered by the Fachschaft, the Institute and the University?
+
+**Well, that is a thing of the past!** That's why we created Portal, a service-aggregating meta-service for over-zealous students like us, the [fsco.li](fsco.li).
+
+
+## What is Portal?
+
+Portal is a service that aggregates all the services that the Fachschaft offers. It is a web application that is accessible via the URL [fsco.li/portal](https://portal.fachschaft.cl.uni-heidelberg.de). It is a service that is designed to be user-friendly and easy to use. It is a service that is designed to be accessible to all students, regardless of their technical background and cognitive abilities.
+
+If you are a rather visual learner, we got you covered:
+
+![This will make the purpose of portal clear once and for all.](info-4-devs/metaservice-badboy.png)
+
+
+## What can you do with Portal?
+
+Most importantly, you can access all the services that the Fachschaft offers in one place. Also, Portal offers
+
++ a neat LDAP integration
++ a Taiga (fsco.li/todo) integration
++ even a f*cking GitLab integration (we are so proud of this one)
++ an user-friendly interface
++ a responsive design (mostly)
+
+# If you are a contributor...
+
+## I want to setup portal on my local machine!
+
+First you gotta clone this repository.
+We advise you to do this with Gitlabs VS Code integration, but you can also use the terminal.
+
+```sh
+git clone https://gitlab.cl.uni-heidelberg.de/Fachschaft/portal.git
+```
+
+Then you have two options:
+
+### ...with docker
 
 To run a flask shell inside the container:
 
@@ -12,7 +48,7 @@ To run a flask shell inside the container:
 sudo docker exec -it portal-app-1 flask shell
 ```
 
-### without docker
+### ...without docker
 
 ```bash
 # mkdir yourself into the portal directory
@@ -65,7 +101,7 @@ What did you expect?
 
 #### `/portal/static/js`: JavaScript files
 
-Lol, that should actually ![have its own README](JS-README.md).
+Lol, that should actually ![have its own README](info-4-devs/JS-README.md).
 
 It contains all the JavaScript files that are responsible for the frontend interactions.
 

info-4-devs/JS-README.md

+# 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`
++ `Me.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.
+