GEWISDB - The GEWIS Decision and Membership Database

GEWISDB is the decision and membership database for GEWIS — GEmeenschap van Wiskunde en Informatica Studenten.

Features

The GEWIS decision and membership database provides the board and other GEWIS systems with lots of functionality:

• Management of Decisions:

  • Organise and manage various types of meetings.
  • Handle a range of decisions, from financial budgets and statements to the installation of members in various organs, along with customisable decisions.
  • While decisions can be altered to reflect changes, they remain more or less immutable to maintain historical accuracy.

• Management of Memberships:

  • The join page, located at join.gewis.nl, facilitates new memberships and can automatically collect membership fees through Stripe.
  • Validation of student information ensures that all member information is accurate.
  • Allows for detailed and precise editing of member information.

• Checker Module:

  • Ensures that the database remains in a consistent state by enforcing many constraints derived from the Articles of Association and Internal Regulations.
  • For instance, it prevents members from being installed in an organ if their membership has expired, ensuring adherence to (regulatory) requirements.

• ReportDB:

  • Provides a consistent "materialised view" of the real database, enabling easy querying of decisions and membership information through an API.
  • Used by most GEWIS systems as a single, reliable source of truth, ensuring consistency and accuracy across all systems.

And there is plenty more! GEWISDB continuously evolves to meet the needs of the association.

Getting Started

GEWISDB is built on PHP and the Laminas MVC framework. The Laminas MVC framework provides a solid foundation for building scalable and maintainable web applications.

Prerequisites

We recommend developing natively on a Linux machine or through WSL2 on Windows (note: Arch-based distributions are not recommended) with the PhpStorm IDE or another IDE with good IntelliSense support for PHP.

You will need at least:

• docker and docker compose (make sure that you have enabled Buildkit)
• gettext utilities
• git
• make
• A .po file editor (e.g. POEdit)

Some of the make commands run natively on your machine; as such, you may also need to install PHP itself (use the ondrej/php PPA for apt to get the latest version) and composer.

Installation

To set up GEWISDB locally, follow these steps:

1. Fork the repository.
2. Clone your fork (git clone git@github.com:{username}/gewisdb.git).
3. Copy the .env.dist file to .env and alter the file to your needs.
4. Run make rundev to build and serve the website (this may take 5-10 minutes).
5. Run make migrate and make seed to get some test data.
6. Go to http://localhost/ in your browser and you are greeted with the GEWIS decision and membership database.
7. Log in with username admin and the password gewisdbgewis.

Contributing

We welcome contributions from the community, especially GEWIS members! To contribute:

1. Perform the steps from Installation.
2. Create your feature of bug fix branch (git switch -c feature/my-amazing-feature).
3. Commit your changes (git commit -m 'feat: added my amazing feature'). NOTE: GEWISDB requires commits to be signed, see this GitHub article for more information on how to sign commits.
4. Push to the branch (git push origin feature/my-amazing-feature).
5. Open a pull request.

More detailed information on GEWIS' contribution guidelines, including conventions on branch names and commit messages, can be found here.

Project Structure

A general overview of important folders required for the functioning of the website:

./
├── config                  # Global configuration files for the website.
├── data                    # Persistent private data-related files, such as cryptographic keys and logs.
├── docker                  # Docker-related files to construct the containers.
├── module                  # Contains the modules that make up the website, each providing specific features.
└── public                  # Publicly accessible files, including the entry point (index.php).

We make use of the Model-View-Controller framework. Generally speaking, the model layer is responsible for the interaction with the database and data manipulation. Next, the view layer is responsible for rendering data into a web page. The controller is responsible for processing the request and interacts with the model and view layer to provide a response.

To make development easier (and due to how the Laminas MVC framework works) we add some extra layers and arrive at a structure for each module that looks like this:

./
├── config
│   └── module.config.php   # Contains routing information and other module specific configurations.
├── src
│   ├── Command             # CLI commands.
│   │   └── ...
│   ├── Controller          # Entrypoint for requests to the website, some light processing takes place here before using a specific service.
│   │   └── ...
│   ├── Form                # Specification and validation of forms based on entities.
│   │   └── ...
│   ├── Mapper              # Doctrine ORM repositories to access the underlying database and mapping entities to that data.
│   │   └── ...
│   ├── Model               # Doctrine ORM entities.
│   │   └── ...
│   └── Service             # Services contain the core logic related to specific entities (or sets of entities) and do most of the processing.
│   │   └── ...
├── test                    # Test files for this module, such as unit tests.
│   ├── Seeder              # Data fixtures to seed the database with data for this module.
│   │   └── ...
│   └── ...
└── view                    # All template files ("views") made out of HTML and PHP code, used by controllers for output.
    └── ...

The Application module has one additional folder:

• language containing the translation files (make translations to update them).

The Database and Report modules have one additional folder:

• migrations containing database migrations.

License

This software is licensed under the GNU General Public License v3.0 (GPL-3.0), see LICENSE.