Compass 🧭

Compass is a web application for the Stadtmuur organization, which allows the participants to record their working hours, track their mood, track exceptional incidents, create daily reports and visualize this information.

For more information navigate to our wiki.

Table of Contents

• Prerequisites
• Project Structure
• Building the Project
  • Backend
  • Frontend
• Running the Project
  • Backend
  • Frontend
• Running Tests
• Additional Information
• Docker and Kubernetes
• Makefile

Prerequisites

This project uses Node.js and Java. We recommend using NVM (Node Version Manager) to manage your Node.js versions. You can switch to the correct Node.js version for this project by running nvm use in the project directory.

For Java, we recommend using a Java Development Kit (JDK) version 21 or above.

Project Structure

.
.
├── README.md                       # Project README with general information
├── backend                         # Backend specific code
│   ├── src                         # Source code for the backend application
│   ├── build.gradle                # Gradle build script for the backend
│   └── settings.gradle             # Gradle settings for the project
├── frontend                        # Frontend specific code
│   ├── .github                     # GitHub workflows and actions configurations
│   ├── .vscode                     # VSCode specific settings
│   ├── migrations                  # Database migrations
│   ├── public                      # Public assets such as images and static files
│   ├── scripts                     # Scripts for building, deploying, etc.
│   ├── src                         # Source code for the frontend
│   │   ├── app                     # Next.js application setup and routing
│   │   ├── components              # Reusable React components
│   │   ├── libs                    # Third-party libraries configuration
│   │   ├── locales                 # Localization and internationalization files
│   │   ├── models                  # Models for structuring database data
│   │   ├── styles                  # CSS and styling files
│   │   ├── templates               # HTML or other templates
│   │   ├── types                   # TypeScript type definitions
│   │   ├── utils                   # Utility functions
│   │   └── validations             # Validation schemas for data input
│   ├── tests                       # Testing suite
│   │   ├── e2e                     # End-to-end testing, possibly including Monitoring as Code
│   │   └── integration             # Integration tests for interconnected components
│   ├── tailwind.config.js          # Tailwind CSS configuration
│   └── tsconfig.json               # TypeScript configuration

Building the Project

Backend

1. Navigate to the backend directory.
2. Run ./gradlew build to build the project.

Frontend

1. Navigate to the frontend directory.
2. Install the necessary dependencies by running npm install.
3. Build the project by running npm run build.

Running the Project

Backend

1. Navigate to the backend directory.
2. Start the server by running ./gradlew bootRun.

Frontend

1. Navigate to the frontend directory.
2. Start the server by running npm run start.

Running Tests

This project uses Jest for unit testing and Playwright for integration and E2E testing. To run the tests, use the following commands:

• Unit tests: npm run test
• Integration & E2E tests:

  npx playwright install
  npm run test:e2e

Refer to the code block from frontend/README.md lines 294-304 for more details.

Additional Information

• Tailwind CSS for styling.
• Sentry for error monitoring.
• Auth0 for authentication.

Docker and Kubernetes

This project can be containerized using Docker and orchestrated with Kubernetes. However, specific instructions for Docker and Kubernetes will depend on your project setup and requirements. Please refer to Docker's official documentation and Kubernetes' official documentation for more information.

Makefile Usage

This project includes a Makefile with commands for building and running different components of the project using Docker. Here are some of the commands you might find useful:

Building Docker Images

• make build-backend: Builds the Docker image for the backend part of the project.

• make build-frontend: Builds the Docker image for the frontend part of the project.

• make build: Builds the Docker images for both the frontend and backend parts of the project.

Running the Project

• make run: Runs the Docker containers for the project using Docker Compose. This command starts up all the services defined in the docker-compose.yml file, including the frontend, backend, and any databases or other dependencies.

• make stop: Stops all running Docker containers associated with the project's Docker Compose configuration. This command brings down all the services that were started with make run.