AYS | Afet Yönetim Sistemi API

Description

Disaster Management System ,which is named as AYS(AFET YÖNETİM SİSTEMİ), is an open source and voluntary project. The aim is to manage the needs that arise during a natural disaster. It manages the coordination of the need processes between volunteers and institutions in the disaster area.

This project is designed to be used by non-governmental organizations and volunteers of related organizations. Organizations and the volunteers to be registered by the organizations, the needs in the disaster area, volunteers who are close to the relevant region and need, aims to manage the needs quickly and accurately.

Processes

Institute (Institution) user Processes : It is aimed to ensure resource management of the organization in case of a disaster and to carry out these processes according to the relevant scenarios. It allocates workloads for volunteers according to the needs and follows up.
Admin : The role of Admin takes part in the management of users and institutions that voluntarily participate in the role. It follows up institutions and users.
User : It represents the users who are in the relevant disaster area and want to take part in disaster processes voluntarily. Users who want to participate voluntarily can contact the relevant organizations for the needs in their region. can be automatically assigned, or interested volunteers can choose from the needs in their region select the most appropriate assignment and complete the relevant process.

Tech Stack

Framework

Core
- Spring
  - Spring Boot 3
  - Spring Boot Test (Junit)
  - Spring Boot Dev Tools
  - Spring Web
  - Spring Boot Actuator
  - Spring Doc Open API
  - Spring Security 6
  - Spring OAuth2 Client
  - Spring OAuth2 Resource Server
- Spring Data
  - Spring Data JPA

3rd Party Dependencies

Lombok
Test Containers
Mapstruct
Easy Random
JSON Web Token
JSON Web Signature
Bouncy Castle

Database

MySQL

Database Migration Tool

Liquibase

Language

Java 17

Build Tool

Maven

Software Development Process

TDD
Agile Kanban
GitHub Projects

Version Control

Git
GitHub

APIs Interaction Platform

Postman

Application Pipeline

GitHub Actions

Getting Started

The project has been generated by Spring Initializer.

Instructions Before Building Project

First of all, generate personal access token with this url : https://github.com/settings/tokens

Before Running Locally On IDE

If you haven't ~/m2/settings.xml file skip the step without reading the after section. If you aren't using the ~/.m2/settings.xml file to actively, you can be back up it before creating the new settings.xml file, if you want. If you are using actively, after the perform step 3 you can manually merge the settings.xml file in the project with the ~/.m2/settings.xml file and skip step 2 and 4.

While inside the project directory in the terminal; that is, when you are in the ~/afet-yonetim-sistemi/ays-be directory, run the command cp template-settings.xml settings.xml.

In the settings.xml file within the project, replace the {YOUR_GITHUB_USERNAME} placeholder with your GitHub username and replace {YOUR_PERSONAL_GITHUB_ACCESS_TOKEN} with the access token value you created on GitHub as described in the instructions under the 'Instructions Before Building The Project' section.

If the .m2 directory has not been created before, you can use the command mkdir ~/.m2 and then run the command cp settings.xml ~/.m2/settings.xml for copy the settings.xml file located in the project to the ~/.m2 directory.

Don't forget to enable Lombok pre-processing in your IDE!

Building The Project With Tests

./mvnw clean install

Building The Project Without Tests

./mvnw clean install -DskipTests

Running as Docker MySQL container

Before running the project, you need to run the following command to start the MySQL container:

docker compose up -d --build database

If you want to recreate the MySQL container, you can run the following command:

docker compose up --force-recreate -d --build database

If you want to stop the MySQL container, you can run the following command:

docker compose down -v database

Running As Docker Container

While inside the project directory in the terminal; that is, when you are in the ~/afet-yonetim-sistemi/ays-be directory, run the command cp template-settings.xml settings.xml.

In the settings.xml file within the project, replace the {YOUR_GITHUB_USERNAME} placeholder with your GitHub username and replace {YOUR_PERSONAL_GITHUB_ACCESS_TOKEN} with the access token value you created on GitHub as described in the instructions under the 'Instructions Before Building The Project' section.

Before running the project, you need to run the following command to start the project container:

docker compose up -d --build

If you want to recreate the project container, you can run the following command:

docker compose up --force-recreate -d --build

If you want to stop the project container, you can run the following command:

docker compose down -v

Running the app with Kubernetes

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

You should be able to see the service, deployment and pods. If you want to access the service using internal IP, try using NodePort instead of LoadBalancer in service.yaml or simply use port forwarding:

kubectl port-forward service/ays-be 9790:9790

How to Contribute

The project is managed by GitHub projects. You can assign an issue from the Todo list and start working on it.

Development Standards

This project uses GitHub flow for collaboration. You can see open issues here. You can start working one of the open issues by assigning it to yourself.

For your feature branches, please ensure below:

Make sure to associate your feature branch with the GitHub issue from 'Development' section in each issue page.
main branch is protected.
PR should be linked to the relevant issue within the GitHub Project.
Your feature branches can be merged by pull request that is approved by at least one code owner.
PR should be squash-merged to avoid having merge commit history.
PR title and description should clearly define and explain the aim.
PR title should contain the issue/feature/bug number e.g. Issue 7 - Readme Update
PR should successfully complete build and any other necessary tests before being merged to main.
Branches should follow the below Naming Conventions of Branchs header.
Each release should be tagged with a version
Commit messages should be subjectless e.g. Add README.md e.g. Fix ...
Comments within the PR should only be resolved by the person who made the comment.
PR should be concise; don't try to fix/introduce more than one thing
Do not include/push secret/credential information
The code should comply with the existing code standards and previously established coding standards. No new standards should be introduced, and if they are, the reasons for their addition should be stated, with the expectation that this structure will be applied to the entire project.
Pull Request Headers should follow the below Naming Conventions of Pull Requests header.

Naming Conventions of Branchs

bugfix/{issue-number}/{optional-description}
- Ex: bugfix/0/authentication-flow or bugfix/0
feature/{issue-number}/{optional-description}
- Ex: feature/0/admin-register-flow or feature/0
refactor/{issue-number}/{optional-description}
- Ex: refactor/0/tests-classes or refactor/0
hotfix/{issue-number}/{optional-description}
- Ex: hotfix/0/authorization-flow or hotfix/0

Naming Conventions of Pull Requests

#{issue-number} | {header-for-summary-of-development}
- Ex: #0 | Authentication/Authorization Flows Has Been Created

Docker Image Name Conventions

Docker images should be tagged as "org-name/project-name:version" e.g. "ays/ays-be:v1.0" "ays/ays-be" indicates the latest version.

Versioning

The project follows the semantic versioning i.e. MAJOR.MINOR.PATCH e.g. v1.9.9.

Project Documents

AYS technical analysis can be found here.

For other information, you can contact the project's Discord channel.

Postman

anilhazar / ays-be