feat: docs

.github/workflows/docs-preview.yaml

@@ -0,0 +1,32 @@
+name: Docs Preview
+on:
+  pull_request: {}
+  push:
+    branches:
+      - dev
+permissions:
+  contents: write
+jobs:
+  preview:
+    name: Preview
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Git
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - name: Install MkDocs
+        run: pip install mkdocs-material
+      - name: Build Docs
+        run: mkdocs build --strict
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-preview
+          path: site/

.github/workflows/docs.yaml

@@ -0,0 +1,35 @@
+name: Docs
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  gh-pages:
+    name: GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Git
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - name: Create Cache ID
+        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - name: Setup Cache
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: ~/.cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Install MkDocs
+        run: pip install mkdocs-material
+      - name: Deploy Docs
+        run: mkdocs gh-deploy --force

README.md

@@ -24,6 +24,8 @@
 
 ## Install
 
+First, you need a running database (i.e. MariaDB). Make sure you have written down connection string, host, port, database name, user name and password.
+
 Clone the repository and install the dependencies:
 
 ```sh
@@ -39,13 +41,22 @@ Copy .env.example to .env and fill in the database credentials.
 cp .env.example .env
 ```
 
+```
+DB_CONNECTION=<connection string>
+DB_HOST=<host (mostly localhost or 127.0.0.1)>
+DB_PORT=<port>
+DB_DATABASE=<database name>
+DB_USERNAME=<user name>
+DB_PASSWORD=<password>
+```
+
 Generate the application key:
 
 ```sh
 php artisan key:generate
 ```
 
-Run the migrations:
+Run the migrations to create database tables:
 
 ```sh
 php artisan migrate
@@ -55,6 +66,12 @@ php artisan migrate
 
 ### development
 
+Before starting the server, seed the database first. This creates the necessary data for the application to work:
+
+```sh
+php artisan db:seed
+```
+
 For development, you can use the built-in PHP server:
 
 ```sh

docs/100-development/.pages

@@ -0,0 +1 @@
+title: Development

docs/100-development/110-general/.pages

@@ -0,0 +1 @@
+title: General

docs/100-development/110-general/111-general.md

@@ -0,0 +1,26 @@
+# General
+
+## Programming Language and Framework
+
+The application is written in [PHP](https://www.php.net/) and uses the [Laravel](https://laravel.com) framework.
+The framework makes common problems such as routing, security, authentication easy to handle. After you learn how Laravel works, it becomes very pleasant to work with. For a detailed documentation, view the [Laravel documentation](https://laravel.com/docs/11.x).
+The frontend is written in [Vue.js](https://vuejs.org/) using [TypeScript](https://www.typescriptlang.org/) and uses [Inertia.js](https://inertiajs.com/) as api-layer to connect the frontend and backend.
+The application is styled with [Tailwind CSS](https://tailwindcss.com/) and uses [Vite](https://vitejs.dev/) as build tool.
+We use [FormKit](https://formkit.com/) to create forms.
+
+## Language
+
+The code and documentation **should be written in English**.
+This ensures that all developers and external contributors can understand the code and documentation.
+
+## MVC-Pattern
+
+Portals uses the widely used Model-View-Controller-Pattern.
+Models are used to read, store and change objects on the database.
+Views are used to display objects and let users interact with them.
+Interactions are sent as requests to controllers. Controllers handle these requests, access data via models and respond with a view or another fitting response (such as JSON).
+
+Models can be found in `app/Models`.
+The corresponding tables are defined in the migration files under `database/migrations`.
+Views can be found in `resources/js`.
+Controllers can be found in `app/Http/Controllers`.

docs/100-development/110-general/112-project-structure.md

@@ -0,0 +1,71 @@
+# Project Structure
+
+To understand the structure of the project, it is helpful to know where to find certain files and folders. The following is a brief overview of the most important directories and their contents.
+
+!!! warning "Laravel Structure"
+
+    Because we dont want to repeat the Laravel documentation, this section only contains a brief overview of the project structure and all "special" files in our case. For the full documentation of the Laravel structure, refer to the [Laravel documentation](https://laravel.com/docs/11.x/structure).
+
+### `.devcontainer/`
+
+Contains configuration files for the [DevContainer](https://code.visualstudio.com/docs/devcontainers/containers) used to develop the project in a consistent environment using docker containers. This is useful to ensure that all developers use the same versions of tools and libraries.
+The devcontainer can be used with [Laravel Sail](https://laravel.com/docs/11.x/sail).
+
+### `.github/`
+
+Contains configuration files for GitHub, such as workflows for continuous integration (CI / [GitHub Actions](https://github.com/features/actions)), issue templates and so on.
+
+### `deploy/`
+
+Contains scripts and configuration files for deploying the project to a server.
+Please refer to the [Deployment documentation](../200-deployment/) for more information.
+
+### `docs/`
+
+Contains this documentation.
+It is written in [Markdown](https://www.markdownguide.org/).
+The documentation is built using [MkDocs Material](https://squidfunk.github.io/mkdocs-material/), which is a static site generator that converts Markdown files into a website.
+
+### `resources/js/components/`
+
+Contains reusable UI components that can be used throughout the pages (views).
+Refer to the [Vue.js documentation](https://vuejs.org/guide/essentials/component-basics) for more information on how to create and use components.
+
+### `resources/js/composables/`
+
+Contains reusable UI logic that can be used in components or pages.
+Refer to the [Vue.js documentation](https://vuejs.org/guide/reusability/composables) for more information on how to create and use composables.
+
+### `resources/js/layouts/`
+
+Contains different website layouts that can be used to structure the pages.
+Layouts are used to define the overall structure of a page, such as the header, footer and sidebar.
+
+### `resources/js/pages/`
+
+Contains the actual pages (views) of the website.
+A page doesnt have to contain all the content of the page, it will be combined with the layout and components to create the final page.
+
+### `resources/js/types/`
+
+Contains different reusable types that can be used throughout the project.
+This is useful to define the structure of objects and ensure type safety in TypeScript.
+The types are **auto generated** using [scrumble-nl/laravel-model-ts-type](https://github.com/scrumble-nl/laravel-model-ts-type).
+
+<!-- TODO: ref to docs where type generation is explained -->
+
+### `resources/js/formkit.*.ts`
+
+Contains the configuration and styling for [FormKit](https://formkit.com/).
+
+### `docker-compose.sail.yaml`
+
+Contains the docker compose configuration for the development environment using [Laravel Sail](https://laravel.com/docs/11.x/sail).
+
+### `docker-compose.yaml`
+
+Contains the docker compose configuration for the production environment.
+
+### `Dockerfile`
+
+Contains the steps to execute when creating a docker container for the project.

docs/100-development/110-general/113-branch-structure.md

@@ -0,0 +1,27 @@
+# Branch Structure
+
+## main
+
+The `main` branch is the primary branch for the project.
+It contains the latest stable code that is ready for production and can be used to create releases.
+**It should not be modified directly.**
+The main branch should only be changed through a [Pull Request](../115-pull-requests.md) (PR) from the `dev` branch.
+
+## dev
+
+The `dev` branch is the development branch where all new features and changes are collected.
+When the code in the `dev` branch is stable and ready for production, it can be merged into the `main` branch using a [Pull Request](../115-pull-requests.md).
+
+## Feature Branches
+
+Feature branches are used for developing new features, bug fixes, or other changes.
+These branches **must be created from the `dev` branch** and should be named according to the feature or issue being worked on.
+
+Example:
+
+- `feat/new-login-system`
+- `fix/login-error`
+
+If you want you can add the issue number to the branch name, e.g. `feat/new-login-system-#123` or `fix/login-error-#456`.
+
+<!-- TODO: merge info from CONTRIBUTING.md -->

docs/100-development/110-general/114-issues.md

@@ -0,0 +1,5 @@
+# Issues
+
+<!-- TODO -->
+
+<!-- TODO: merge info from CONTRIBUTING.md -->

docs/100-development/110-general/115-pull-requests.md

@@ -0,0 +1,5 @@
+# Pull Requests
+
+<!-- TODO -->
+
+<!-- TODO: merge info from CONTRIBUTING.md -->

docs/100-development/120-backend/.pages

@@ -0,0 +1 @@
+title: Backend

docs/100-development/120-backend/121-backend.md

@@ -0,0 +1,3 @@
+# Backend
+
+<!-- TODO -->

docs/200-deployment/.pages

@@ -0,0 +1 @@
+title: Deployment

docs/200-deployment/201-deployment.md

@@ -0,0 +1,3 @@
+# Deployment
+
+<!-- TODO -->

docs/300-usage/.pages

@@ -0,0 +1 @@
+title: Usage

docs/300-usage/301-usage.md

@@ -0,0 +1,3 @@
+# Usage
+
+<!-- TODO -->

docs/index.md

@@ -0,0 +1,18 @@
+# Welcome to Portals
+
+Portals is a web application that is mainly used for group application.
+It was originally developed for the "Ersti-Woche" (Freshman Week) and "Ersti-Fahrt" (Freshman Trip).
+
+The application is developed by the "Fachschaftsrat Elektro- und Informationstechnik" (Student Council for Electrical and Information Engineering) of the Fachhochschule Aachen (University of Applied Sciences Aachen) and is mainly used by them too. But others are welcome to use it as well.
+
+## Short Feature Overview
+
+- Developers can create different events in the application code with different register times and group sizes.
+- Users can register for events which are divided into groups.
+- Administrators can start the division of users into groups. The division algorithm can be configured to balance groups by courses or other criteria.
+- Group tutors can overview their groups and mark members as present or missing.
+- The tool can handle different aspects like requirements for groups (e.g. payment), waiting lists, and more.
+
+## Demo Mode
+
+Feel free to clone the repository and run the application locally (see [Setup Guide](../100-development/110-setup/)) to checkout all features.

mkdocs.yaml

@@ -0,0 +1,32 @@
+site_name: Portals
+site_url: https://fsr-fhaachen.github.io/portals/
+theme:
+  name: material
+  features:
+    - search.suggest
+    - search.highlight
+    - navigation.tabs
+    - navigation.footer
+    - content.action.view
+    - content.action.edit
+  palette:
+    primary: teal
+  icon:
+    repo: fontawesome/brands/github
+  language: en
+plugins:
+  - search
+  - awesome-pages
+  - git-revision-date-localized:
+      enable_creation_date: true
+  - git-committers:
+      repository: fsr-fhaachen/portals
+      branch: main
+repo_url: https://github.com/fsr-fhaachen/portals
+repo_name: fsr-fhaachen/portals
+edit_uri: edit/main/docs/
+copyright: Copyright © 2025 Fachschaftsrat Elektro- und Informationstechnik der Fachhochschule Aachen
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences

requirements.txt

@@ -0,0 +1,4 @@
+mkdocs-material
+mkdocs-awesome-pages-plugin
+mkdocs-git-revision-date-localized-plugin
+mkdocs-git-committers-plugin-2