Peepol

Peepol is a comprehensive person management platform designed to be robust, secure, and easy to deploy. This repository contains both the backend (API) and the frontend (Web).

The simplest way to get the entire ecosystem up and running is by using Docker Compose. This will automatically configure the PostgreSQL database, the Backend service, and the Frontend application.

1. Clone the repository:

   git clone https://github.com/jelvi00/peepol.git
   cd peepol

2. Configure the environment: Copy the sample environment variables file to a new .env file:

   cp .env.sample .env

   Please change .env values to desired ones.

3. Build and start the containers:

   docker compose --env-file .env up -d

4. Access the application:

   • Frontend (Web): http://localhost:3000
   • Backend (API): http://localhost:4556/peepol-api

• Java 21 with Spring Boot 3.5.
• Gradle Convention Plugins: Centralized build logic using Kotlin DSL in buildSrc.
• Spring Security with PASETO (Platform-Agnostic Security Tokens) authentication.
• MapStruct 1.6 for efficient Entity-DTO mapping.
• Liquibase for database version control.
• PostgreSQL 16 as the main database.
• Gradle as the dependency and build manager.

• Next.js 16 (App Router) and React 19.
• Tailwind CSS 4 for styling.
• Pnpm as the package manager.
• Jest and React Testing Library for unit testing.
• Playwright for end-to-end (E2E) testing.

The system includes an administrator user automatically created through database migrations.

• Default System User: [configure it in .env]
• Registration: New users can be registered through the API with ADMIN privileges.
• Authentication (BE): /auth/login.
• Authentication (FE): /login.
• Good to know: Since http cookie is declared as secure, a https connection is required to access the application. See how cookies are managed at AuthService.setSessionCookies on the frontend.

Note: Security is managed via PASETO tokens, which offer a more modern and secure alternative to traditional JWTs.

Run the full suite of unit and integration tests:

./gradlew :backend:test

JaCoCo coverage reports are automatically generated after the tests.

• Unit Tests: cd frontend && pnpm test
• E2E Tests: cd frontend && pnpm test:e2e

The project includes a Bruno collection for testing the API endpoints.

1. Install Bruno from the official website.
2. Open Bruno and select "Open Collection".
3. Browse to the bruno folder in the root of this project.
4. The collection includes:
   • Admin: Login, Registration, Person Deletion, and Platform Status monitoring.
   • User: Operations for Person management (Get, Search, Add, Update).

Make sure the backend is running before executing requests.

Each module has its own optimized Dockerfile (multi-stage builds) for production:

• Backend: Lightweight image based on JRE 21 with a non-root user.
• Frontend: Uses Next.js standalone mode to minimize image size.

To stop all services:

docker compose down