diff --git a/.github/workflows/docs-preview.yaml b/.github/workflows/docs-preview.yaml new file mode 100644 index 00000000..8cd1c909 --- /dev/null +++ b/.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/ diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..88ead336 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index 16661ee3..646c6637 100644 --- a/README.md +++ b/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= +DB_HOST= +DB_PORT= +DB_DATABASE= +DB_USERNAME= +DB_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 diff --git a/docs/100-development/.pages b/docs/100-development/.pages new file mode 100644 index 00000000..a4ffc334 --- /dev/null +++ b/docs/100-development/.pages @@ -0,0 +1 @@ +title: Development diff --git a/docs/100-development/110-general/.pages b/docs/100-development/110-general/.pages new file mode 100644 index 00000000..994701e1 --- /dev/null +++ b/docs/100-development/110-general/.pages @@ -0,0 +1 @@ +title: General diff --git a/docs/100-development/110-general/111-general.md b/docs/100-development/110-general/111-general.md new file mode 100644 index 00000000..166ee2fd --- /dev/null +++ b/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/pages`. +Controllers can be found in `app/Http/Controllers`. diff --git a/docs/100-development/110-general/112-project-structure.md b/docs/100-development/110-general/112-project-structure.md new file mode 100644 index 00000000..fd43403d --- /dev/null +++ b/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). + + + +### `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. diff --git a/docs/100-development/110-general/113-branch-structure.md b/docs/100-development/110-general/113-branch-structure.md new file mode 100644 index 00000000..c541e502 --- /dev/null +++ b/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`. + + diff --git a/docs/100-development/110-general/114-issues.md b/docs/100-development/110-general/114-issues.md new file mode 100644 index 00000000..b660d9f3 --- /dev/null +++ b/docs/100-development/110-general/114-issues.md @@ -0,0 +1,39 @@ +# Issues + +We use GitHub issues to manage and document tasks for this project. This includes features, bugfixes, tests etc. + +Issues can be granular tasks or more general, like an observation of a bug or a feature request. Title and description must be clear in what is asked for. If possible, the description should provide ideas on how to solve the issue. + +## Labels + +We use labels to classify our issues. + +### Priority + +Every issue needs to be prioritised: + +- Low: Can be done if nothing else needs to be done +- Medium: Would be nice to have for the next release +- High: Must be finished for the next release + +### Good first issue + +This means that the solution for the issue is not complex, so it can be used as a first task for new contributors. + +### Javascript/php + +If it is clear, it can be classified which type of code will be changed be this issue. + +### Task type + +- Bug: application error that needs to be addressed +- Enhancement: something like a new feature or performance increase +- Dependencies: update for dependencies + +### Other labels + +There are further labels which are self explanatory. + +## Branches + +For each issue, a new branch is created. Every new branch is based on the dev-branch. Refer to the [branch structure](./113-branch-structure.md) for more information about naming, commits etc. diff --git a/docs/100-development/110-general/115-pull-requests.md b/docs/100-development/110-general/115-pull-requests.md new file mode 100644 index 00000000..8d74a302 --- /dev/null +++ b/docs/100-development/110-general/115-pull-requests.md @@ -0,0 +1,14 @@ +# Pull Requests + + + +If you have completed your development on a branch, you have to create a pull request. +The pull request must be pointed against the `dev` branch (see [Branches](./113-branch-structure.md)). + +The pull request title should be in the same pattern as the commit messages (see [Commits](./116-commits.md)), because the pull request title is used as the merge commit message. + +Please update the labels of the PR accordingly. + +After submitting the pull request, it will be reviewed and if everything is fine, it will be merged into the `dev` branch. + +Every change to the `dev` branch will be merged to the `main` branch later on. diff --git a/docs/100-development/110-general/116-commits.md b/docs/100-development/110-general/116-commits.md new file mode 100644 index 00000000..136407f2 --- /dev/null +++ b/docs/100-development/110-general/116-commits.md @@ -0,0 +1,19 @@ +# Commits + +We are using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for our commits. +Every commit must follow this pattern. + +The commit message is split into different parts: + +- **Commit type**. (e.g. `feat`, `fix`, `chore`, `ci`, `test`, ...) +- **Changed module/component** in brackets. If you want to target a sub module/component you can add it after the module/component and separate it with a slash `/`. + Example: `(devcontainer)` or `(tests/e2e)`. If no module/component fits, you can leave this part out completely. + Please don't use `*` as module/component or add empty brackets `()`. +- **A colon `:`** to separate the type and module/component from the commit message. +- **Commit message**. All messages must be in english and follow the conventions of the conventional commits standard. + They must be written in the imperative, present tense. Example: "change" not "changed" nor "changes". The first letter should not be capitalized. + +The resulting commit message should look like this: + +- `feat(devcontainer): add documentation` +- `fix: remove typo` diff --git a/docs/100-development/120-backend/.pages b/docs/100-development/120-backend/.pages new file mode 100644 index 00000000..e0c3f621 --- /dev/null +++ b/docs/100-development/120-backend/.pages @@ -0,0 +1 @@ +title: Backend diff --git a/docs/100-development/120-backend/121-backend.md b/docs/100-development/120-backend/121-backend.md new file mode 100644 index 00000000..15d13e64 --- /dev/null +++ b/docs/100-development/120-backend/121-backend.md @@ -0,0 +1,9 @@ +# Backend + +Portals uses the [Laravel](https://laravel.com) Framework, currently version 11.
+For the backend, the most important concepts are [Routing](https://laravel.com/docs/11.x/routing), [Middleware](https://laravel.com/docs/11.x/middleware) and [Controllers](https://laravel.com/docs/11.x/controllers). + +To summarize: A user request first gets intercepted by middleware, which can for example check if a user is authenticated. The routing component then determines the action that should be performed based on the URL. Usually, the routing delegates to a function which is defined in a controller.
+Such functions read on the database via [models](https://laravel.com/docs/11.x/eloquent), perform server side logic, and then return a view or a JSON response. + +For more detailed explanations as well as further concepts used in this project, refer to the official Laravel documentation. diff --git a/docs/100-development/120-backend/122-data-structure.md b/docs/100-development/120-backend/122-data-structure.md new file mode 100644 index 00000000..f19cf345 --- /dev/null +++ b/docs/100-development/120-backend/122-data-structure.md @@ -0,0 +1,4 @@ +# Data Structure + +This ERD contains the tables and relations for events like Erstiwoche or Erstifahrt: +![ERD](./ERD/Portals-ERD.png) diff --git a/docs/100-development/120-backend/123-group-division.md b/docs/100-development/120-backend/123-group-division.md new file mode 100644 index 00000000..7b959e68 --- /dev/null +++ b/docs/100-development/120-backend/123-group-division.md @@ -0,0 +1,35 @@ +# Group Division + +Certain events are split into groups. The division process is automated with algorithms you can find in `app/Helpers`. + +## Forms of division + +There are multiple forms of division: + +### Balanced Division + +Balanced division means that every group has a user course ratio that is roughly equal to the total ratio of the event. + +### Course Division + +Every group only has users with certain courses. + +### Slot Assignment + +An event can have slots with limited user count. Users need to register for slots. The slots then get assigned. The first users to register get assigned first. If a slot is full, the remaining registrations will get assigned to a queue. + +## Parameters + +There are different parameters to consider when dividing users into groups: + +### Consider Alcohol / Minimum non drinkers + +If alcohol is considered, then every group must have either 0 non dinkers, or the configured minimum amount. This is to ensure that noone is the only sober person in the group. + +### Maximum amount of groups + +This parameter controls how many groups are allowed to be created. + +### Maximum group size + +This controls how many users a group can have. diff --git a/docs/100-development/120-backend/ERD/Portals-ERD.drawio b/docs/100-development/120-backend/ERD/Portals-ERD.drawio new file mode 100644 index 00000000..41e1dc68 --- /dev/null +++ b/docs/100-development/120-backend/ERD/Portals-ERD.drawio @@ -0,0 +1,711 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/100-development/120-backend/ERD/Portals-ERD.png b/docs/100-development/120-backend/ERD/Portals-ERD.png new file mode 100644 index 00000000..1ed7672a Binary files /dev/null and b/docs/100-development/120-backend/ERD/Portals-ERD.png differ diff --git a/docs/100-development/130-frontend/.pages b/docs/100-development/130-frontend/.pages new file mode 100644 index 00000000..832f5f94 --- /dev/null +++ b/docs/100-development/130-frontend/.pages @@ -0,0 +1 @@ +title: Frontend diff --git a/docs/100-development/130-frontend/131-frontend.md b/docs/100-development/130-frontend/131-frontend.md new file mode 100644 index 00000000..a1d908e6 --- /dev/null +++ b/docs/100-development/130-frontend/131-frontend.md @@ -0,0 +1,3 @@ +# Frontend + + diff --git a/docs/200-deployment/.pages b/docs/200-deployment/.pages new file mode 100644 index 00000000..ffcae26c --- /dev/null +++ b/docs/200-deployment/.pages @@ -0,0 +1 @@ +title: Deployment diff --git a/docs/200-deployment/201-deployment.md b/docs/200-deployment/201-deployment.md new file mode 100644 index 00000000..d8d0b57f --- /dev/null +++ b/docs/200-deployment/201-deployment.md @@ -0,0 +1,3 @@ +# Deployment + + diff --git a/docs/300-usage/.pages b/docs/300-usage/.pages new file mode 100644 index 00000000..65d1e0c8 --- /dev/null +++ b/docs/300-usage/.pages @@ -0,0 +1 @@ +title: Usage diff --git a/docs/300-usage/301-usage.md b/docs/300-usage/301-usage.md new file mode 100644 index 00000000..03083da5 --- /dev/null +++ b/docs/300-usage/301-usage.md @@ -0,0 +1,3 @@ +# Usage + + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..f831eddd --- /dev/null +++ b/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. diff --git a/mkdocs.yaml b/mkdocs.yaml new file mode 100644 index 00000000..e53e7f3b --- /dev/null +++ b/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 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..6cd20b70 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +mkdocs-material +mkdocs-awesome-pages-plugin +mkdocs-git-revision-date-localized-plugin +mkdocs-git-committers-plugin-2