Spring Dashboarding Project - AI Coding Instructions

Project Overview

This is a Spring Boot 4.0.2 dashboarding application using Java 25 with PostgreSQL, organized as a modular monolith using Spring Modulith. The architecture emphasizes module boundaries through package structure.

Architecture & Module Structure

Module Organization

Package = Module boundary: Each package under
```
nl.kabisa.dashboarding
```
represents a distinct module
Current modules:
- ```
restservice
```
  : REST API endpoints (example: greeting service)
- ```
dashboard
```
  : JPA entity management for dashboards with PostgreSQL/JSONB
- ```
widget
```
  : Widget management with encrypted secrets and configuration validation
Spring Modulith enforces module boundaries - modules communicate via well-defined interfaces, not direct package access

Key Technologies

Spring Boot 4.0.2 with Spring Modulith 2.0.2
Java 25 (uses modern features like records)
PostgreSQL 16 with JSONB support
JPA/Hibernate with automatic schema updates (Jackson databind for JSON support)
Springdoc OpenAPI 3.0.0 for auto-generated API documentation
Maven wrapper for builds (use
```
./mvnw
```
, not global Maven)

Development Workflows

Database Setup

docker compose up # Starts PostgreSQL container

Database credentials in application.properties:

dashboarduser/dashboardpass

localhost:5432/dashboarddb

Running the Application

./mvnw spring-boot:run

Or use VS Code's "Run: DashboardingApplication" terminal configuration.

Testing

./mvnw test

Use
```
@SpringBootTest
```
with
```
@AutoConfigureMockMvc
```
for integration tests
Examples:
- GreetingControllerTest.java
- DashboardControllerTest.java

Code Conventions & Patterns

REST Controllers

Place in module-specific packages (e.g.,
```
restservice
```
)
Use
```
@RestController
```
with
```
@GetMapping
```
/
```
@PostMapping
```
Example pattern in GreetingController.java

DTOs & Value Objects

Use Java records for immutable DTOs:

public record Greeting(long id, String content)

See Greeting.java for reference

JPA Entities

Standard JPA annotations with lifecycle callbacks (
```
@PrePersist
```
,
```
@PreUpdate
```
)

Use

@JdbcTypeCode(SqlTypes.JSON)

with

columnDefinition = "jsonb"

for PostgreSQL JSON columns

UUID primary keys with

@GeneratedValue(strategy = GenerationType.UUID)

Soft deletes via
```
deletedAt
```
timestamps
Example: Dashboard.java

Widget secrets are encrypted/decrypted in entity lifecycle callbacks
Use
```
EncryptionUtil
```
with PBKDF2-derived AES keys
Reuse a shared
```
ObjectMapper
```
(static or injected); do not instantiate per call
Catch specific exceptions (e.g.,
```
JsonProcessingException
```
,
```
GeneralSecurityException
```
) with descriptive messages

Repositories

Extend
```
JpaRepository<Entity, ID>
```
interface
Mark with
```
@Repository
```
annotation
Example: DashboardRepository.java

API Documentation

Swagger/OpenAPI Support

Auto-generated OpenAPI documentation via Springdoc OpenAPI 3.0.0
JSON endpoint:
```
http://localhost:8080/api-docs
```
Swagger UI:
```
http://localhost:8080/swagger-ui.html
```
Configured in application.properties

Important Notes

Always use
./mvnw
(Maven wrapper) instead of system Maven for consistency
Database schema auto-updates via
```
spring.jpa.hibernate.ddl-auto=update
```
- suitable for learning, not production
Spring DevTools enabled for automatic reloading during development
Jackson databind is required for JSON/JSONB mapping with Hibernate

Spring Dashboarding Project - AI Coding Instructions

Project Overview

Architecture & Module Structure

Module Organization

Package = Module boundary: Each package under
```
nl.kabisa.dashboarding
```
represents a distinct module
Current modules:
- ```
restservice
```
  : REST API endpoints (example: greeting service)
- ```
dashboard
```
  : JPA entity management for dashboards with PostgreSQL/JSONB
- ```
widget
```
  : Widget management with encrypted secrets and configuration validation
Spring Modulith enforces module boundaries - modules communicate via well-defined interfaces, not direct package access

Key Technologies

Spring Boot 4.0.2 with Spring Modulith 2.0.2
Java 25 (uses modern features like records)
PostgreSQL 16 with JSONB support
JPA/Hibernate with automatic schema updates (Jackson databind for JSON support)
Springdoc OpenAPI 3.0.0 for auto-generated API documentation
Maven wrapper for builds (use
```
./mvnw
```
, not global Maven)

Development Workflows

Database Setup

docker compose up # Starts PostgreSQL container

Database credentials in application.properties:

dashboarduser/dashboardpass

localhost:5432/dashboarddb

Running the Application

./mvnw spring-boot:run

Or use VS Code's "Run: DashboardingApplication" terminal configuration.

Testing

./mvnw test

Use
```
@SpringBootTest
```
with
```
@AutoConfigureMockMvc
```
for integration tests
Examples:
- GreetingControllerTest.java
- DashboardControllerTest.java

Code Conventions & Patterns

REST Controllers

Place in module-specific packages (e.g.,
```
restservice
```
)
Use
```
@RestController
```
with
```
@GetMapping
```
/
```
@PostMapping
```
Example pattern in GreetingController.java

DTOs & Value Objects

Use Java records for immutable DTOs:

public record Greeting(long id, String content)

See Greeting.java for reference

JPA Entities

Standard JPA annotations with lifecycle callbacks (
```
@PrePersist
```
,
```
@PreUpdate
```
)

Use

@JdbcTypeCode(SqlTypes.JSON)

with

columnDefinition = "jsonb"

for PostgreSQL JSON columns

UUID primary keys with

@GeneratedValue(strategy = GenerationType.UUID)

Soft deletes via
```
deletedAt
```
timestamps
Example: Dashboard.java

Widget secrets are encrypted/decrypted in entity lifecycle callbacks
Use
```
EncryptionUtil
```
with PBKDF2-derived AES keys
Reuse a shared
```
ObjectMapper
```
(static or injected); do not instantiate per call
Catch specific exceptions (e.g.,
```
JsonProcessingException
```
,
```
GeneralSecurityException
```
) with descriptive messages

Repositories

Extend
```
JpaRepository<Entity, ID>
```
interface
Mark with
```
@Repository
```
annotation
Example: DashboardRepository.java

API Documentation

Swagger/OpenAPI Support

Auto-generated OpenAPI documentation via Springdoc OpenAPI 3.0.0
JSON endpoint:
```
http://localhost:8080/api-docs
```
Swagger UI:
```
http://localhost:8080/swagger-ui.html
```
Configured in application.properties

Important Notes

Always use
./mvnw
(Maven wrapper) instead of system Maven for consistency
Database schema auto-updates via
```
spring.jpa.hibernate.ddl-auto=update
```
- suitable for learning, not production
Spring DevTools enabled for automatic reloading during development
Jackson databind is required for JSON/JSONB mapping with Hibernate

Spring Dashboarding Project - AI Coding Instructions

Related Skills

Markdown Converter

Nano Banana Pro

1password