Skip to content

docs: update README with project summary and technical details #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Tyreviel merged 1 commit into from
Apr 24, 2026
Merged

docs: update README with project summary and technical details #102

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 81 additions & 108 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,147 +1,120 @@
# Projekt-arendehantering
# Trauma Team - Case Management System

Spring Boot application for case management with a Thymeleaf UI, PostgreSQL, and MinIO.
A robust, full-stack Spring Boot application designed for medical case management, featuring a clean MVC architecture, hybrid authentication, and cloud-native document storage.

## Prerequisites
## Project Summary

- Java 25
- Docker Desktop (or Docker Engine with Compose)
- Maven Wrapper (`mvnw`) is included in the project
The "Trauma Team Case Management" project provides a secure platform for managing patient cases, employee assignments, and medical documentation. It follows strict architectural guardrails to ensure scalability, security, and maintainability.

## Start the application (local development)
### Key Features

<<<<<<< issue/69
### Quick start (recommended on Windows)
- **Case Management:** Full lifecycle management of medical cases (Create, Read, Update, Delete, Close).
- **Hybrid Authentication:**
- **Patients:** Register and login using traditional email/password credentials.
- **Employees/Managers:** Secure login via **GitHub OAuth2** integration.
- **Role-Based Access Control (RBAC):** Fine-grained permissions for Patients, Employees, and Managers.
- **Document Management:** Attach documents to cases with secure storage in **S3-compatible** systems (MinIO/Cloudflare R2).
- **Resilience:** Built-in retry logic for file operations and background processing for failed S3 deletions.
- **Auditing:** Automatic audit logging of key system events and user actions.
- **Caching:** Performance optimization using **Caffeine** for frequent data lookups.
- **Responsive UI:** Modern, clean web interface built with **Thymeleaf** and Vanilla CSS.

Run one command to perform all startup steps:
## Technologies Used

```powershell
.\start-local.ps1
```
### Backend
- **Java 25**
- **Spring Boot 4.0.4**
- **Spring Data JPA** (Persistence)
- **Spring Security** (Authentication & Authorization)
- **Spring Cloud AWS** (S3 Integration)
- **Spring Retry** (Resilience)

Show full command output instead of fun/quiet mode:
### Database & Infrastructure
- **PostgreSQL** (Production/Development Database)
- **H2** (In-memory testing)
- **MinIO** (Local S3-compatible storage)
- **Docker & Docker Compose** (Containerized infrastructure)

```powershell
.\start-local.ps1 --serious
```

The script will:
- Verify Docker is available and the engine is running
- Start infrastructure with `docker compose up -d`
- Start Spring Boot with profile `local`
### Frontend
- **Thymeleaf** (Server-side templating)
- **Vanilla CSS** (Custom styling)
- **Apache Tika** (MIME type detection)

=======
>>>>>>> main
### 0) Verify Docker is running (Windows)
### Developer Tools
- **Lombok** (Boilerplate reduction)
- **Spotless** (Code formatting)
- **Maven** (Build automation)
- **GitHub Actions** (CI/CD)

Before running `docker compose up -d`, make sure Docker Desktop is started and the Linux engine is running.
---

1. Start Docker Desktop.
2. Wait until Docker Desktop shows **Engine running**.
3. Verify in PowerShell:
## Getting Started

```powershell
docker version
```
### Prerequisites

If Docker is healthy, this command prints both `Client` and `Server` sections.
- Java 25
- Docker Desktop (or Docker Engine with Compose)
- Maven Wrapper (`mvnw`) is included in the project

If you get an error like:
### 1. Start Infrastructure Services

`open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified`
The project uses Docker Compose to run PostgreSQL and MinIO.

it means Docker Desktop is not running (or not fully started yet). Start/restart Docker Desktop, wait 10-30 seconds, then run `docker version` again.
```powershell
# Quick start (recommended on Windows)
.\start-local.ps1
```
Comment on lines +65 to +66

@coderabbitai coderabbitai Bot Apr 24, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Use OS-specific Maven wrapper commands to prevent Windows setup failures.

Line 65 is Windows-oriented, but Line 88 uses Unix-style ./mvnw. On PowerShell/CMD, this should typically be .\mvnw.cmd ....

Proposed doc tweak 
 ### 3. Run the Application
 
 ```bash
 ./mvnw spring-boot:run -Dspring-boot.run.profiles=local

+powershell +.\mvnw.cmd spring-boot:run "-Dspring-boot.run.profiles=local" +

</details>


Also applies to: 87-89

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @README.md around lines 65 - 66, The README currently shows Unix-style Maven
wrapper usage (./mvnw) and a Windows-oriented script name (start-local.ps1)
inconsistently; update the doc to include OS-specific Maven wrapper examples by
adding a PowerShell/CMD variant using .\mvnw.cmd (or mvnw.cmd for CMD) alongside
the existing ./mvnw example and ensure the Windows example includes quoted
JVM/property args as in "-Dspring-boot.run.profiles=local", and mirror this
change for the other occurrences around the current mvnw examples.


</details>

<!-- fingerprinting:phantom:triton:hawk:1032491a-9086-4874-8b86-a18b0d7af6de -->

<!-- This is an auto-generated comment by CodeRabbit -->


### 1) Start infrastructure services
Or manually:

```bash
docker compose up -d
```

This starts:
- PostgreSQL on `localhost:5432`
- MinIO API on `localhost:9000`
- MinIO Console on `localhost:9001`
- **PostgreSQL:** `localhost:5432`
- **MinIO API:** `localhost:9000`
- **MinIO Console:** `localhost:9001`

### 2) Start the Spring Boot application with the local profile
### 2. Configure GitHub OAuth2

```bash
./mvnw spring-boot:run -Dspring-boot.run.profiles=local
```
To use GitHub login, you need to set your environment variables:
- `GITHUB_CLIENT_ID`
- `GITHUB_CLIENT_SECRET`

On Windows PowerShell:
### 3. Run the Application

```powershell
.\mvnw spring-boot:run "-Dspring-boot.run.profiles=local"
```bash
./mvnw spring-boot:run -Dspring-boot.run.profiles=local
```

### 3) Open the app

- [http://localhost:8080](http://localhost:8080)

## Login and access
The application will be available at [http://localhost:8080](http://localhost:8080).

### Admin account (use normal login page)
## Access and Roles

There is no separate admin login page. Use the normal login form at [http://localhost:8080/login](http://localhost:8080/login).
### Admin/Manager Account
A default manager account is seeded when running with the `local` profile:
- **Email:** `admin@traumateam.com`
- **Password:** `password`
- **Role:** `MANAGER`

When running with profile `local`, an admin-level account is seeded from `data-local.sql`:
### Patient Access
Patients can register at `/register` and manage their own cases.

- Email: `admin@traumateam.com`
- Password: `password`
- Role: `MANAGER`
### Employee Access
Employees should use the "Sign in with GitHub" option on the login page.

Log in with:
---

- Username/Email: `admin@traumateam.com`
- Password: `password`
## Project Structure

### Other login options
The project follows a strict **MVC** architecture:
- `presentation`: REST and Web controllers, DTOs.
- `application`: Business logic (Services), Mappers.
- `infrastructure`: Persistence (Entities, Repositories), Security configuration, Cloud config.
- `common`: Cross-cutting concerns (Exceptions, Shared Models).

- Patients can register via `/register` and then log in with email/password at `/login`.
- Employees can use GitHub OAuth via the "Sign in with GitHub" button on `/login`.

## Stop services

```bash
docker compose down
```

## Quick troubleshooting

- `docker compose up -d` fails with pipe/engine error:
- Start Docker Desktop and wait until the engine is green/running.
- Re-run `docker version` and confirm `Server` appears.
- PostgreSQL fails with `Bind for 0.0.0.0:5432 failed: port is already allocated`:
- Another process (often a local PostgreSQL service) already uses port `5432`.
- Find what owns the port in PowerShell:

```powershell
netstat -ano | findstr :5432
```

- Note the PID in the last column, then check process name:

```powershell
tasklist /FI "PID eq <PID>"
```

- If it is a local PostgreSQL/service you do not need right now, stop it and retry:

```powershell
Stop-Service -Name postgresql* -ErrorAction SilentlyContinue
docker compose up -d
```
## Troubleshooting

- If you want to keep your local PostgreSQL running, map Docker PostgreSQL to another host port:
<<<<<<< issue/69
1. Edit `docker-compose.yml` PostgreSQL ports from `"5432:5432"` to `"5433:5432"`.
2. Edit `src/main/resources/application.properties` database URL from `localhost:5432` to `localhost:5433`.
3. Run `docker compose up -d` again.
=======
1. Edit `docker-compose.yml` PostgreSQL ports from `"5432:5432"` to `"5433:5432"`.
2. Edit `src/main/resources/application.properties` database URL from `localhost:5432` to `localhost:5433`.
3. Run `docker compose up -d` again.
>>>>>>> main
- App starts but login fails:
- Confirm you started Spring with profile `local` so `data-local.sql` is loaded.
- **Port Conflicts:** If port `5432` is in use, stop any local PostgreSQL services or modify the mapping in `docker-compose.yml` and `application.properties`.
- **Docker Issues:** Ensure Docker Desktop is running and the Linux engine is active. Use `docker version` to verify.