employees-fullstack

Full-stack Example / Reference Application (Spring Boot 4 · Java 25 · Angular 20)

CI

Spring Boot Java Angular

Application screenshot

💻 Source code

The complete source code is available on GitHub: https://github.com/MorganShirl/employees-fullstack

🧭 Who this project is for

🎯 Project Goal

This project is a minimal but production-oriented starter kit / reference application intended to kickstart modern full-stack development.

It demonstrates real-world security concerns, including:

The emphasis is on clarity, correctness, and modern best practices, with sensible defaults and configuration files that include only what is strictly required for the application to run correctly.

In particular, the POM files, .gitignore, .editorconfig, application.yml, application-postgres.yml, angular.json, tsconfig.json, app.config.ts, styles.scss are intentionally kept minimal and explicit.

In other words, there is no superfluous or dead code.

ℹ️ Project Information

Build tooling is provisioned via the Maven Wrapper and a frontend Maven plugin.
As a result, the only prerequisite to build and run the project is a Java 25 JDK.

Development was done using IntelliJ IDEA Ultimate 2025.
While other IDEs can be used, IntelliJ is recommended, as the repository includes IDE-specific run configurations and database connection files that are referenced in the Development section below.

✨ Key Features

The project provides a focused set of features commonly required in real-world production systems, available from the outset.

It consists of a parent Maven POM and two child modules:

During the build, the frontend Maven plugin packages the Angular application directly into the Spring Boot executable JAR.

The frontend can also be run independently and communicate with the backend, making it possible to explicitly test CORS (cross-origin) and same-origin (proxy-based) configurations.

☕🌱 Backend (Spring Boot 4 / Java 25)

🅰️ Frontend (Angular 20)

🛠️ Development

🧱 Building the project

It is better to build the project using the Maven Wrapper to ensure that the correct Maven version is used (see maven-wrapper.properties).

Commands on Windows:

   cd ./employees-fullstack/

   ./mvnw.cmd clean install

On a Linux machine:

   ./mvnw clean install

Or you can use the IntelliJ maven run config:
👉 employees-fullstack [clean,install]

▶️ Running the backend

You can run the backend using the IntelliJ Spring Boot run configurations provided in the .idea/runConfigurations folder.
👉 SbBackendApplication [default h2]
👉 SbBackendApplication [postgres]

Backend endpoint

http://localhost:8090/

Predefined users & authentication

Test users with username/email/password are defined in:
👉 AppConfig.java
When you log in, you will see a JSESSIONID cookie in the application tab of Chrome DevTools.
When you log out, this cookie is removed.

Actuator endpoints

http://localhost:9090/actuator
Also see 👉 actuator.http
To see the DB caches: http://localhost:9090/actuator/caches

Swagger endpoint

http://localhost:8090/swagger-ui/index.html

Virtual threads verification endpoint

http://localhost:8090/api/info/request-thread

All these endpoints are accessible thanks to

👉 SpaForwardFilter.java

Backend testing via IntelliJ HTTP Requests (backend must be running of course)

You can test the backend by running the IntelliJ httpRequests test suite provided in the .httpRequests folder.
👉 crud-employees-test.http

Run the backend with the postgres profile

To use the PostgreSQL run configuration, make sure Docker Desktop is running, then start the containers:

   cd ./employees-fullstack/

   docker compose up -d

The pgadmin console is available (you have to wait a bit after starting the containers).
To connect to this console, see the credentials in application-postgres.yml and docker-compose.yml, then go to:
http://localhost:5050

To stop the containers:

   docker compose down

To stop the containers AND delete all data stored in the postgres-employees-data Docker volume:

   docker compose down -v

Run the backend with the default h2 profile

With the default profile, the data is stored in a h2 db in ./employees-fullstack/data

The h2 console is available here:
http://localhost:8090/h2

▶️ Running the frontend

   cd ./angular-frontend/employees-ui/

http://localhost:4200/

1. Run without the Angular proxy (direct backend calls — CORS enabled)

   ng serve

Or you can run the frontend using the IntelliJ run configuration provided in the .idea/runConfigurations folder.
👉 employees-ui [CORS].

This mode makes the browser call the backend at http://localhost:8090 directly from http://localhost:4200, so the origins are different.
You will see real CORS preflight (OPTIONS) requests in the network tab of Chrome DevTools.
If you remove http://localhost:4200 from app.cors.allowed-origins in application.yml, you will see CORS errors.

2. Run with the Angular proxy (no CORS)

ng serve --configuration=proxy

Or you can run the frontend using the IntelliJ run configuration provided in the .idea/runConfigurations folder.
👉 employees-ui [start proxy - no CORS].

This mode proxies all /api calls from the Angular dev server to http://localhost:8090, so the browser never makes cross-origin requests.
You will see no CORS preflight (OPTIONS) requests.

This mirrors the behavior obtained when the application is served directly by the backend at http://localhost:8090 after a Maven build.

🚧 404 handling

http://localhost:8090/api/employees/99
=> backend 404:
{“detail”:”Could not find employee with id [=99]”,”instance”:”/api/employees/99”,”status”:404,”title”:”Resource Not Found”}

http://localhost:8090/employees/99 => frontend handles that and returns the custom 404 page from employees-ui

http://localhost:8090/notExist => frontend handles that and returns the custom 404 page from employees-ui

This site is open source. Improve this page.