Beer Review Application - Group 2522

A full-stack beer review application built with JavaFX frontend and Spring Boot backend, allowing users to browse beers and manage reviews.

Public site

Web frontend is available at https://ontappd.graesberg.com, with api available at /api

Eclipse che

Open repository in Eclipse Che - remember to set your personal access token first

NOTE: We have had some problems with Eclipse Che and to run it you need to follow our quickstart for eclipse che as described below.

NOTE: Not all function of our shell script work cleanly in Che, as we cannot connect to the docker container running the postgres server. Please watch the output of ./scriptappd.sh to see if there are any instructions

Quickstart for Eclipse Che (You need to run this in order to use eclipse che)

1. Open the terminal (The menu icon -> Terminal -> New terminal)

./scriptappd.sh migrate-with-fixtures

# **If you get "/projects/gr2522/backend/run-migrations.sh: line 17: psql: command not found" run this and try to run the bash script again:
# sudo apt install -y postgresql-client

2. Run the backend and frontend (Its recommended to split the terminal. Or just make a another one)

./scriptappd.sh run:app

# Or in seperate terminals
./scriptappd.sh run:backend

# for the frontend
./scriptappd.sh run:frontend

3. Under endpoints in the VScode sidebar, open desktop-ui in a new tab and you should see the login-screen

Prerequisites

• Java 21 or higher
• Maven 3.8.5 or higher
• Docker and docker-compose
• Python, pip and pre-commit

Contributing

Before contributing to this repository, please install pre-commit and the hooks to ensure the formatting is correct.
To do this, run the following commands:

pip install pre-commit

pre-commit install

Now pre-commit will run before every commit, and check that formatting and linting is correct

Quickstart

To quickly run the project, please follow these simple steps:

1. Ensure the docker engine is running. The most common ways of doing this is by opening Docker desktop, or running the dockerd command in a seperate shell
2. Run ./scriptappd.sh migrate-with-fixtures (Replace ./scriptappd.sh with ./scriptappd-win.ps1 if you are on windows) to run migrations and seed the db with fixtures
3. Run ./scriptappd.sh run:app to launch both the frontend and the backend!

Note: The frontend might launch before the backend is ready to receive requests. In this case, the frontend will load mock data instead of the fixtures. Simply click into a beer, then return to overview to see the data from the backend.

Architecture

The application consists of two main components:

Backend

• Technology: Spring Boot REST API
• Database: PostgreSQL
• Purpose: Manages beer data and reviews through REST endpoints
• Port: localhost:8080

Frontend

• Technology: JavaFX desktop application
• Purpose: User interface for browsing beers and managing reviews
• Features: Beer list view, detailed beer information, review creation

Web

• Technology: React web frontend with TanStack router
• Purpose: Web-based user interface for browsing beers and managing reviews

Project Structure

gr2522/
├── backend/                        # Spring Boot REST API
│   ├── src/main/java/              # Java source code
│   │   └── it1901/gr2522/backend/
│   │       ├── BeerController.java # REST endpoints
│   │       ├── model/              # Data models
│   │       └── db/                 # Database access layer
│   └── src/main/resources/
│       ├── application.properties  # Spring configuration
│       └── db/
│           ├── migrations/         # Database schema
│           └── fixtures/           # Sample data
├── frontend/                       # JavaFX application
│   ├── src/main/java/              # Java source code
│   │   └── it1901/gr2522/frontend/
│   │       ├── MainApp.java        # Application entry point
│   │       ├── controller/         # UI controllers
│   │       ├── model/              # Data models
│   │       └── service/            # API communication
│   └── src/main/resources/         # FXML layouts and resources
├── web/                            # React web frontend
│   ├── src
│   │   ├── components              # React components
│   │   ├── integrations
│   │   ├── logo.svg
│   │   ├── main.tsx
│   │   └── routes                  # Available routes
├── docs/                           # Documentation
├── docker-compose.yaml             # PostgreSQL database setup
├── scriptappd.sh                   # Custom script for easily running development-related commands
└── scriptappd-win.ps1              # scriptappd.sh translated to windows powershell for windows users

Running the app

We have written a custom bash script, and had AI translate it to powershell, so that we can easily run complicated commands related to the testing, development and running of the fullstack application. wherever scriptappd.sh is mentioned, scriptappd-win.ps1 can be used instead for windows users, with the same arguments.

Our app is split into a backend project and a frontend project. If you have node installed, you can simply run the command ./scriptappd.sh run:app to start both at the same time. run:backend and run:frontend are also avaliable.

**NOTE: ** Because the backend stores persistent data in a postgres database, you must start the docker container for it, and run the migrations to ensure the database has the correct schema. You can also migrate with fixtures, if you want mock-data in the tables. To run all this, run the following commands:

# Ensure the docker daemon is running, either by launching docker desktop, or (linux only) by running dockerd in another shell session

./scriptappd.sh migrate # To ensure the database has the correct schema, OR
./scriptappd.sh migrate-with-fixtures # To ensure the database has the correct schema, and is populated with mock data

# Then, to start the app
./scriptappd.sh run:app

If you are developing the frontend, it is reccommended to run ./scriptappd.sh run start:frontend and ./scriptappd.sh run start:backend in two seperate shell sessions, as maven does not support hot reloading, and this way you save time by only restarting the frontend when changes are made.

Testing

To run the tests either run ./scriptappd.sh test to run all tests, or ./scriptappd.sh run test:backend or ./scriptappd.sh run test:frontend to run the indivdual components. If you wish to use mvn test you first need to open the frontend or backend directories. You can also use run mvn -f backend test and mvn -f frontend test to test them from the root.

API Endpoints

The backend provides the following REST endpoints:

• GET /api/beers - Get all beers (lightweight list)
• GET /api/beers/{id} - Get specific beer with reviews
• POST /api/beers/{id} - Add a review to a specific beer

User Stories

Here are some key functionalities of this project from the user's perspective:

1. View Beer List on Home Page

As a user
I want to be able to see a list of beers on the home page
So that I can browse available beers and discover new options

2. Log In and Sign Up

As a user
I want to be able to make my own account with a unique username and log in to it
So that I can make reviews under my name and can log in again

3. Add Personal Beer Reviews

As a user
I want to be able to add my own reviews after I have clicked into a beer
So that I can share my experience and opinion with other users

4. Add New Beer As An Admin

As a Developer
I want to be able to easily add new beers in the frontend
So that I can save time and energy rather than writing the JSON myself or append it directly to the database

Features

Beer Management

• Browse a curated list of beers
• View detailed beer information (name, brewery, style, ABV)
• See beer images and descriptions

Review System

• View all reviews for a specific beer
• Add new reviews with star ratings (1-5)
• Include reviewer name and detailed comments
• Calculate average ratings automatically

Data Persistence

• PostgreSQL database for reliable data storage
• Database migrations for schema management
• Sample data fixtures for development and testing

Development

Individual Component Development

Backend only:

./scriptappd.sh run start:backend

Frontend only:

./scriptappd.sh run start:frontend

Database Management

Reset database:

./scriptappd.sh run nuke-db

Re-run migrations:

./scriptappd.sh run migrate
# or with sample data
./scriptappd.sh run migrate-with-fixtures

Documentation

• Backend Documentation - Detailed backend setup and API documentation
• Frontend Documentation - Frontend architecture and usage

Technology Stack

• Backend: Spring Boot 3.5.5, PostgreSQL, Maven
• Frontend: JavaFX, Jackson (JSON processing), Maven
• Development: Docker Compose, ./scriptappd.sh scripts for workflow automation