spring-boot-backend

Spring Boot Backend Development - Photo Map MVP

Project Context

Stack: Spring Boot 3.2.11+, Java 17 LTS, PostgreSQL 15, Spring Security 6 (JWT stateless)

Core Features:

Authentication - JWT login/registration, BCrypt hashing
Photo Management - Upload with EXIF extraction, asynchronous processing, CRUD operations
User Scoping - Strict data isolation (users see only their own photos)
Admin API - User management (ADMIN role)

Key Constraints:

MVP scope - simple solutions preferred
Mikrus VPS - limited resources (synchronous API, async background processing)
User isolation CRITICAL - ALL queries MUST include userId filtering

Architecture Principles

Layered Architecture

Controller (HTTP only) → Service (business logic) → Repository (data access) → Database

User Scoping Pattern (CRITICAL)

All photo queries MUST include userId to enforce data isolation:

// ❌ BAD: Security vulnerability - any user can access any photo public Photo getPhoto(final Long photoId) { return photoRepository.findById(photoId).orElseThrow(); }

// ✅ GOOD: User can only access their own photos public Photo getPhoto(final Long photoId, final Long userId) { return photoRepository.findByIdAndUserId(photoId, userId) .orElseThrow(() -> new ResourceNotFoundException("Photo not found")); }

Transaction Management

Use @Transactional on service methods
Read operations: @Transactional(readOnly = true)
Write operations: @Transactional (default)

For detailed architecture: See references/architecture.md for:

ALL 5 SOLID principles (SRP, OCP, LSP, ISP, DIP)
Design patterns (Constructor Injection, Static Factory Methods)
Service orchestration patterns

When to Use What

Code Quality

Use final keyword: Method params, local variables, injected dependencies → references/java-quality.md
Modern Java 17: Records for DTOs, Text Blocks for SQL, Stream.toList() → references/java-quality.md

Architecture

@Service: Business logic, orchestrates repositories → references/architecture.md
@Component: Utilities, non-business services
Records: Immutable response DTOs → references/rest-api-patterns.md
@Data classes: Request DTOs with validation → references/rest-api-patterns.md

Data Access

Derived queries: Simple queries (findByUserId) → references/jpa-patterns.md
@Query (JPQL): Complex queries with multiple conditions → references/jpa-patterns.md
Native SQL: Database-specific features, performance optimization → references/jpa-patterns.md

Async Processing

Spring Integration File: Photo upload processing → references/async-processing.md

Implementation Workflows

REST Endpoint Workflow

Step-by-step guide: templates/rest-endpoint-template.md

Quick checklist:

Create DTO (Record for response, @Data for request) → references/rest-api-patterns.md
Create/Update Entity with User relationship → references/jpa-patterns.md
Create Repository with user scoping methods → references/jpa-patterns.md
Implement Service with @Transactional → templates/service-template.md
Create Controller with proper HTTP status codes → references/rest-api-patterns.md

Complete examples: examples/photo-controller.java , examples/photo-service.java , examples/photo-repository.java

Service Implementation

Template: templates/service-template.md

Key rules:

Constructor injection with final fields (@RequiredArgsConstructor)
@Transactional(readOnly = true) for read operations
All methods MUST accept userId parameter (user scoping)
Throw ResourceNotFoundException when not found
Log at appropriate levels (debug, info, error)

Security & JWT

Complete patterns: references/security-jwt.md

Quick setup:

SecurityConfig: examples/security-config.java
JWT Token Provider: examples/jwt-token-provider.java
User Entity with UserDetails: examples/user-entity.java

Testing

Unit tests: Service layer with Mockito → references/testing.md

Controller tests: MockMvc with @WebMvcTest → references/testing.md

Coverage requirement: >70% for new code

Key Reminders

Security (CRITICAL)

✅ User scoping: ALL photo queries include userId
✅ JWT validation: Token signature & expiration checked on every request
✅ BCrypt passwords: Never store plain text
✅ DTOs only: Never expose entities to API

Performance

✅ @Transactional(readOnly = true) for queries
✅ Database indexes on user_id, frequently queried columns
✅ FetchType.LAZY for relationships
❌ NO premature optimization - keep simple for MVP

MVP Scope

✅ Implement only features from .ai/prd.md
✅ Synchronous processing for API, asynchronous for photo processing
✅ Simple solutions over complex ones
❌ NO features beyond MVP requirements

Quick Reference

File Structure for Feature

src/main/java/com/photomap/ ├── controller/ # {Resource}Controller.java ├── service/ # {Resource}Service.java ├── repository/ # {Resource}Repository.java ├── model/ # {Resource}.java (Entity) └── dto/ # {Resource}Dto.java, {Resource}CreateRequest.java

Pattern Lookup

Need Solution Reference

REST endpoint Follow layered architecture templates/rest-endpoint-template.md

User scoping findByIdAndUserId() references/jpa-patterns.md

Validation Bean Validation annotations references/validation.md

Security JWT + Spring Security references/security-jwt.md

Async processing Spring Integration File references/async-processing.md

Testing Mockito + MockMvc references/testing.md

Database changes Flyway migrations references/database-migrations.md

Naming Conventions

Controller: {Resource}Controller (e.g., PhotoController)
Service: {Resource}Service (e.g., PhotoService)
Repository: {Resource}Repository (e.g., PhotoRepository)
Entity: {Resource} (e.g., Photo)
DTO: {Resource}Dto , {Resource}CreateRequest

spring-boot-backend

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

doc-update

skill-creator

project planning for photo map mvp