Forfafa Spring Boot Development Assistant

Provides expert guidance for working with Forfafa, a Spring Boot-based OAuth user registration system built with Kotlin and Java 21.

Project Context

Forfafa is a production-ready OAuth authentication service supporting Naver and Kakao providers with JWT authentication. It follows Domain-Driven Design (DDD) principles with clean architecture, using PostgreSQL as the primary database and TestContainers for integration testing.

**Technology Stack:**

Instructions

1. Project Setup and Environment

When setting up or troubleshooting the development environment:

1. **Initial Setup:**

- Run `./scripts/local-setup.sh` for complete Docker and environment setup

- Copy `.env.example` to `.env` and configure OAuth credentials

- Verify services with `./scripts/health-check.sh`

2. **Required Environment Variables:**

- `NAVER_CLIENT_ID`, `NAVER_CLIENT_SECRET`: Naver OAuth credentials

- `KAKAO_CLIENT_ID`, `KAKAO_CLIENT_SECRET`: Kakao OAuth credentials

- `JWT_SECRET`: Secure key for JWT signing (critical for production)

- Database credentials: `SPRING_DATASOURCE_URL`, `SPRING_DATASOURCE_USERNAME`, `SPRING_DATASOURCE_PASSWORD`

3. **Health Checks:**

- Check OAuth provider status: `GET /api/auth/oauth/status`

- Verify database connectivity before running application

2. Development Commands

**Build and Run:**

```bash

./gradlew bootRun # Run application locally

./gradlew build # Build JAR

./gradlew clean build # Clean build

```

**Docker Operations:**

```bash

docker-compose up --build # Start local development

docker-compose up --build -d # Start detached

docker-compose logs -f app # View logs

docker-compose down # Stop services

docker-compose -f docker-compose.prod.yml up --build -d # Production

```

**Database Management:**

```bash

Connect to PostgreSQL

docker-compose exec postgres psql -U forfafa_user -d forfafa

Manual schema execution (if needed)

docker-compose exec postgres psql -U forfafa_user -d forfafa < src/main/resources/schema.sql

```

3. Architecture Understanding

**Package Structure (Layered Architecture):**

- Handle HTTP requests/responses

- Define API contracts with DTOs

- Global exception handling

- `oauth/`: OAuth authentication service

- `user/`: User registration service

- Domain events for decoupled communication

- `oauth/`: OAuth value objects and entities (OAuthAccount, OAuthProfile, OAuthProvider)

- `user/`: User aggregate root with value objects (User, Email, UserId)

- Repository interfaces (persistence contracts)

- `oauth/`: OAuth client implementations (Naver/Kakao WebClient)

- `persistence/`: JPA entities and repository implementations

- `security/`: JWT token provider and authentication filter

**Key Design Patterns:**

4. OAuth Flow Implementation

When working with OAuth authentication:

1. **OAuth Flow Steps:**

- Client requests OAuth URL: `GET /api/auth/oauth/{provider}`

- User authenticates with provider

- Provider redirects to callback with authorization code

- Application exchanges code for access token

- Application fetches user profile from provider

- User created/updated, JWT issued

2. **OAuth Configuration:**

- Redirect URIs must exactly match provider dashboard configuration

- Check provider status before testing flows

- Use `OAuthClientFactory` for provider-specific implementations

5. Testing Strategy

**Test Structure:**

- `UserTest`, `EmailTest`, `OAuthAccountTest`

- `OAuthAuthenticationServiceTest`, `UserRegistrationServiceTest`

- `JwtTokenProviderTest`, `NaverOAuthClientTest`

- `JwtSecurityIntegrationTest`: JWT authentication flow

- `OAuthFlowIntegrationTest`: Complete OAuth authentication

- `OAuthErrorScenariosIntegrationTest`: Error handling

- `OAuthPerformanceIntegrationTest`: Performance benchmarks

**Running Tests:**

```bash

./gradlew test # All tests

./gradlew test --tests "*Integration*" # Integration tests only

./gradlew test --tests "*Unit*" # Unit tests only

./gradlew test --tests "JwtSecurityIntegrationTest" # Specific test

./gradlew test --tests "*Performance*" # Performance tests

```

**Kotlin Test Conventions:**

6. Kotlin Development Patterns

**Code Conventions:**

**Architecture Patterns:**

**Key Files for Architecture:**

7. Security and JWT

**Security Architecture:**

**Important Security Notes:**

8. Best Practices

When working with the codebase:

1. **Always verify OAuth configuration status before testing flows**

2. **Use provided scripts for environment setup** (`./scripts/local-setup.sh`)

3. **Follow DDD principles**: Keep business logic in domain layer

4. **Use Kotlin idioms**: Data classes, null safety, extension functions

5. **Write tests in Kotlin** with descriptive backtick function names

6. **Check health endpoints** before troubleshooting issues

7. **Review domain events** for understanding business workflows

8. **Consult repository interfaces** in domain layer for persistence contracts

Example Usage

**Setting up development environment:**

```bash

Clone repository and navigate to project

cd forfafa

Copy environment template

cp .env.example .env

Edit .env with OAuth credentials (required)

Run complete setup

./scripts/local-setup.sh

Verify all services are healthy

./scripts/health-check.sh

Run application

./gradlew bootRun

```

**Testing OAuth flow:**

```bash

Check OAuth provider configuration

curl http://localhost:8080/api/auth/oauth/status

Run OAuth integration tests

./gradlew test --tests "OAuthFlowIntegrationTest"

Run all integration tests

./gradlew test --tests "*Integration*"

```

**Adding a new OAuth provider:**

1. Create provider-specific client in `infrastructure/oauth/`

2. Implement `OAuthClient` interface

3. Register in `OAuthClientFactory`

4. Add provider credentials to `.env` and configuration

5. Write integration tests for the new provider

Constraints