Expert guidance for developing Forfafa, a Kotlin/Spring Boot OAuth user registration system with JWT authentication, PostgreSQL, and DDD architecture
Provides expert guidance for working with Forfafa, a Spring Boot-based OAuth user registration system built with Kotlin and Java 21.
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:**
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
**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
docker-compose exec postgres psql -U forfafa_user -d forfafa
docker-compose exec postgres psql -U forfafa_user -d forfafa < src/main/resources/schema.sql
```
**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:**
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
**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:**
**Code Conventions:**
**Architecture Patterns:**
**Key Files for Architecture:**
**Security Architecture:**
**Important Security Notes:**
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
**Setting up development environment:**
```bash
cd forfafa
cp .env.example .env
./scripts/local-setup.sh
./scripts/health-check.sh
./gradlew bootRun
```
**Testing OAuth flow:**
```bash
curl http://localhost:8080/api/auth/oauth/status
./gradlew test --tests "OAuthFlowIntegrationTest"
./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
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/forfafa-spring-boot-development-assistant/raw