Skip to content

Commit 4187cde

Browse files
author
Joern Wellniak
committed
Description for KI
1 parent cf6e5cb commit 4187cde

10 files changed

Lines changed: 295 additions & 156 deletions

File tree

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,3 +36,7 @@ frontend/node_modules/
3636
frontend/dist/
3737
frontend/.angular/
3838
frontend/package-lock.json
39+
.DS_Store
40+
.classpath
41+
.project
42+
.settings

‎ARCHITECTURE.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Architecture Overview
2+
3+
## Target Architecture
4+
- **Backend:** Spring Boot (Java 21) as API layer
5+
- **Frontend:** Angular 18 SPA
6+
- **Monorepo:** Backend in the root, frontend in `/frontend`
7+
- **Persistence/Infra (Tests):** Testcontainers (e.g., PostgreSQL) for reproducible integration environments
8+
9+
## High-Level Diagram
10+
11+
```mermaid
12+
graph LR
13+
A[Angular 18 SPA] -->|HTTP/JSON| B[Spring Boot API]
14+
B --> C[(Persistence / External Systems)]
15+
```
16+
17+
## Principles
18+
- **Clear API Contract**
19+
- **Configurability** via `application.yml`
20+
- **Testability first:** `@SpringBootTest` > `@WebMvcTest`
21+
- **Automated Quality:** Unit/Integration Tests, Linting, CI

‎BACKEND.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Backend (Spring Boot, Java 21)
2+
3+
## Tech Stack
4+
- Java 21, Spring Boot
5+
- Build: Maven
6+
- Test: JUnit 5, AssertJ, Testcontainers
7+
8+
## Layers
9+
- api: Controllers + DTOs
10+
- application: Services, Use Cases
11+
- domain: Entities, Ports
12+
- infrastructure: Repositories, Adapters, Config

‎FRONTEND.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Frontend (Angular 18)
2+
3+
## Setup
4+
```bash
5+
cd frontend
6+
npm ci
7+
```
8+
9+
## Development
10+
```bash
11+
npm start
12+
```
13+
14+
## API Configuration
15+
```ts
16+
export const environment = {
17+
production: false,
18+
apiBaseUrl: 'http://localhost:8080'
19+
};
20+
```

‎README.md‎

Lines changed: 29 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -1,162 +1,45 @@
1-
# Skat Backend
1+
# skat
22

3-
Spring Boot REST API backend for the Skat application.
3+
Monorepo with **Backend (Java 21, Spring Boot)** at the root level and **Frontend (Angular 18)** in the `frontend` folder.
44

5-
## Technology Stack
6-
7-
- **Java**: 21
8-
- **Spring Boot**: 3.5.6
9-
- **Database**: PostgreSQL (production), H2 (development)
10-
- **Build Tool**: Maven
11-
12-
## Prerequisites
13-
14-
- Java 21 or higher
15-
- Maven 3.6 or higher
16-
- PostgreSQL (for production mode)
17-
18-
## Getting Started
19-
20-
### Running with H2 In-Memory Database (Development)
21-
22-
The easiest way to start the application for development is using the H2 in-memory database:
23-
24-
```bash
25-
mvn spring-boot:run -Dspring-boot.run.profiles=dev
26-
```
27-
28-
The application will start on `http://localhost:8080`
29-
30-
### Running with PostgreSQL (Production)
31-
32-
1. Ensure PostgreSQL is running and create a database:
33-
```sql
34-
CREATE DATABASE skatdb;
35-
```
36-
37-
2. Update the database credentials in `src/main/resources/application.properties` if needed:
38-
```properties
39-
spring.datasource.url=jdbc:postgresql://localhost:5432/skatdb
40-
spring.datasource.username=postgres
41-
spring.datasource.password=postgres
42-
```
43-
44-
3. Start the application:
45-
```bash
46-
mvn spring-boot:run
47-
```
48-
49-
### Building the Application
50-
51-
To build the application and create an executable JAR:
52-
53-
```bash
54-
mvn clean package
55-
```
56-
57-
The JAR file will be created in the `target/` directory.
58-
59-
### Running the JAR
60-
61-
After building, you can run the application using:
62-
63-
```bash
64-
# With H2 (development)
65-
java -jar target/backend-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev
66-
67-
# With PostgreSQL (production)
68-
java -jar target/backend-0.0.1-SNAPSHOT.jar
69-
```
70-
71-
## Running Tests
72-
73-
Execute the test suite:
74-
75-
```bash
76-
mvn test
77-
```
78-
79-
## API Endpoints
80-
81-
### Hello World Endpoint
82-
83-
- **URL**: `/api/hello`
84-
- **Method**: `GET`
85-
- **Response**: Plain text "Hallo"
86-
87-
Example:
88-
```bash
89-
curl http://localhost:8080/api/hello
90-
```
91-
92-
## Configuration Profiles
93-
94-
### Development Profile (`dev`)
95-
96-
Uses H2 in-memory database. Configuration file: `application-dev.properties`
97-
98-
- Database: H2 in-memory
99-
- H2 Console: Enabled at `/h2-console`
100-
- SQL logging: Enabled
101-
102-
### Default Profile (Production)
103-
104-
Uses PostgreSQL database. Configuration file: `application.properties`
105-
106-
- Database: PostgreSQL
107-
- Connection pooling: HikariCP (default)
108-
109-
## Project Structure
5+
## Structure
1106

1117
```
112-
backend/
113-
├── src/
8+
.
9+
├── .github/workflows/build.yml
10+
├── frontend/ # Angular 18 App
11+
├── src/ # Spring Boot Backend (Java 21)
11412
│ ├── main/
115-
│ │ ├── java/
116-
│ │ │ └── com/skat/backend/
117-
│ │ │ ├── SkatBackendApplication.java # Main application class
118-
│ │ │ └── controller/
119-
│ │ │ └── HelloWorldController.java # REST controller
120-
│ │ └── resources/
121-
│ │ ├── application.properties # Production config
122-
│ │ └── application-dev.properties # Development config
12313
│ └── test/
124-
│ └── java/
125-
│ └── com/skat/backend/
126-
│ └── controller/
127-
│ └── HelloWorldControllerTest.java # Controller tests
128-
├── pom.xml # Maven configuration
129-
└── README.md # This file
14+
├── target/
15+
├── pom.xml
16+
└── README.md
13017
```
13118

132-
## Troubleshooting
133-
134-
### Port Already in Use
19+
- **Backend:** Spring Boot (Java 21), REST API
20+
- **Frontend:** Angular 18, consumes backend API
21+
- **Tests:** JUnit 5 + AssertJ (Given-When-Then), **@SpringBootTest** (preferred over `@WebMvcTest`), **Testcontainers** for integration/DB tests
13522

136-
If port 8080 is already in use, you can change it by adding to your run command:
23+
## Quickstart
13724

25+
### Backend
13826
```bash
139-
mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=8081
27+
# Requires Java 21
28+
./mvnw spring-boot:run
29+
# or
30+
./mvnw test
14031
```
14132

142-
### Database Connection Issues
143-
144-
- Verify PostgreSQL is running: `pg_isready`
145-
- Check PostgreSQL logs for connection errors
146-
- Verify database credentials in `application.properties`
147-
148-
## Development
149-
150-
### Adding New Dependencies
151-
152-
Add dependencies to `pom.xml` and run:
153-
33+
### Frontend
15434
```bash
155-
mvn clean install
35+
cd frontend
36+
npm ci
37+
npm start
15638
```
15739

158-
### Code Style
159-
160-
The project follows standard Java coding conventions. Ensure your IDE is configured to use:
161-
- Tab size: 4 spaces
162-
- Charset: UTF-8
40+
## Documentation
41+
- [ARCHITECTURE.md](./ARCHITECTURE.md)
42+
- [BACKEND.md](./BACKEND.md)
43+
- [FRONTEND.md](./FRONTEND.md)
44+
- [TESTING.md](./TESTING.md)
45+
- ADRs: see `docs/architecture/decisions/`

‎TESTING.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Testing Strategy
2+
3+
We test using **Given-When-Then** and **AssertJ**.
4+
**@SpringBootTest** is preferred over **@WebMvcTest**.
5+
**Testcontainers** provides reproducible integration environments.
6+
7+
## Example
8+
```java
9+
@SpringBootTest
10+
@Testcontainers
11+
class ExampleIT {
12+
@Container
13+
static PostgreSQLContainer<?> db = new PostgreSQLContainer<>("postgres:16-alpine");
14+
15+
@Test
16+
void example() {
17+
assertThat(db.isRunning()).isTrue();
18+
}
19+
}
20+
```

‎docs/architecture/decisions/ADR-001-Testing-Strategy-IT.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# ADR-001: Testing Strategy with SpringBootTest and Testcontainers
2+
3+
Date: 2025-10-23
4+
5+
## Status
6+
7+
Accepted
8+
9+
## Context
10+
11+
Integration tests are essential to verify the interaction between multiple components of the system,
12+
including the database, external services, and the application itself. These tests aim to ensure
13+
that the system behaves as expected in a realistic environment.
14+
15+
## Decision
16+
17+
To achieve reliable and maintainable integration tests, we adopt the following tools and practices:
18+
19+
- **@SpringBootTest**: This annotation is used to load the full application context, enabling tests
20+
to run in an environment close to production.
21+
- **Testcontainers**: We use Testcontainers to provide lightweight, disposable containers for
22+
external dependencies such as PostgreSQL. This ensures that tests are isolated and reproducible.
23+
- **Given-When-Then**: Tests are structured using the Given-When-Then pattern to improve readability
24+
and maintainability.
25+
- **AssertJ**: Assertions are written using AssertJ for a fluent and expressive API.
26+
27+
### Key Practices
28+
29+
1. **Database Integration**: Testcontainers is configured to spin up a PostgreSQL container for each
30+
test run, ensuring a clean and isolated database state.
31+
2. **Configuration Management**: Application properties are overridden in the test environment to
32+
connect to the Testcontainers-managed database.
33+
3. **Test Coverage**: Focus is placed on testing critical integration points, such as repository
34+
methods, service-to-service communication, and REST API endpoints.
35+
4. **Performance Considerations**: While integration tests are slower than unit tests, they provide
36+
higher confidence in the correctness of the system.
37+
38+
## Consequences
39+
40+
- **Advantages**:
41+
- High confidence in the correctness of the system as a whole.
42+
- Tests run in an environment that closely resembles production.
43+
- Reduced risk of integration issues in production.
44+
45+
- **Disadvantages**:
46+
- Longer execution times compared to unit tests.
47+
- Increased complexity in test setup and maintenance.
48+
49+
### Maven Configuration (JUnit 5)
50+
```xml
51+
<build>
52+
<plugins>
53+
54+
<!-- Integration tests (see ADR-001) -->
55+
<plugin>
56+
<groupId>org.apache.maven.plugins</groupId>
57+
<artifactId>maven-failsafe-plugin</artifactId>
58+
<version>3.2.5</version>
59+
<executions>
60+
<execution>
61+
<goals>
62+
<goal>integration-test</goal>
63+
<goal>verify</goal>
64+
</goals>
65+
<configuration>
66+
<includes>
67+
<include>**/*IT.java</include>
68+
<include>**/*ITCase.java</include>
69+
</includes>
70+
</configuration>
71+
</execution>
72+
</executions>
73+
</plugin>
74+
</plugins>
75+
</build>
76+
```

0 commit comments

Comments
 (0)