Capstone Project — Building a Complete Blog Platform

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENTS                                  │
│   Browser    Mobile App    Postman    Other APIs                │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTPS
┌──────────────────────────▼──────────────────────────────────────┐
│                      NGINX (Reverse Proxy)                      │
│   • SSL Termination                                             │
│   • Static file serving (/api/files/)                           │
│   • Rate limiting                                               │
│   • Gzip compression                                            │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTP (port 8080)
┌──────────────────────────▼──────────────────────────────────────┐
│                 SPRING BOOT APPLICATION                          │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                   Security Filter Chain                     │ │
│  │  CORS → JWT Filter → Authorization Filter                  │ │
│  └──────────────────────────┬─────────────────────────────────┘ │
│                              │                                   │
│  ┌──────────────────────────▼─────────────────────────────────┐ │
│  │                    Controller Layer                         │ │
│  │  AuthController  PostController  UserController             │ │
│  │  FileController  CategoryController  AdminController        │ │
│  │  • Receives HTTP requests                                   │ │
│  │  • Validates input (@Valid)                                  │ │
│  │  • Returns HTTP responses                                   │ │
│  └──────────────────────────┬─────────────────────────────────┘ │
│                              │                                   │
│  ┌──────────────────────────▼─────────────────────────────────┐ │
│  │                     Service Layer                           │ │
│  │  AuthService  PostService  UserService  CommentService      │ │
│  │  UploadService  CategoryService  TagService                 │ │
│  │  • Business logic & validation                              │ │
│  │  • Transaction management (@Transactional)                  │ │
│  │  • DTO ↔ Entity conversion                                  │ │
│  │  • Caching (@Cacheable, @CacheEvict)                        │ │
│  └──────────────────────────┬─────────────────────────────────┘ │
│                              │                                   │
│  ┌──────────────────────────▼─────────────────────────────────┐ │
│  │                   Repository Layer                          │ │
│  │  UserRepository  PostRepository  CommentRepository          │ │
│  │  CategoryRepository  TagRepository  UploadedFileRepository  │ │
│  │  • JpaRepository interfaces                                 │ │
│  │  • Derived queries, @Query (JPQL/native)                    │ │
│  │  • Pagination and sorting                                   │ │
│  └──────────────────────────┬─────────────────────────────────┘ │
│                              │                                   │
│  ┌──────────────────────────▼─────────────────────────────────┐ │
│  │             Hibernate / JPA / HikariCP                      │ │
│  │  • ORM mapping (Entity ↔ Table)                             │ │
│  │  • SQL generation                                           │ │
│  │  • Connection pooling                                       │ │
│  └──────────────────────────┬─────────────────────────────────┘ │
└──────────────────────────────┼──────────────────────────────────┘
                               │ JDBC (port 3306)
┌──────────────────────────────▼──────────────────────────────────┐
│                       MariaDB 11                                 │
│   • blogdb database                                              │
│   • Flyway-managed schema (V1–V13 migrations)                    │
│   • InnoDB engine, utf8mb4 charset                               │
│   • Indexes for query performance                                │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│                     FILESYSTEM                                    │
│   /var/data/blog-api/uploads/                                     │
│   ├── posts/      (cover images)                                  │
│   └── avatars/    (user avatars)                                  │
└──────────────────────────────────────────────────────────────────┘

users ──────────┐
  │              │
  │ 1:1          │ 1:N
  ▼              ▼
user_profiles   posts ◄──── categories (N:1)
                  │
                  ├─── comments (1:N, self-referencing for replies)
                  │
                  └─── post_tags ───► tags (M:N)
                  │
                  └─── uploaded_files (1:1 cover image)

users ──── uploaded_files (1:1 avatar)

V1__create_users_table.sql
V2__create_categories_table.sql
V3__create_tags_table.sql
V4__create_posts_table.sql
V5__create_post_tags_table.sql
V6__create_comments_table.sql
V7__add_views_count_to_posts.sql
V8__add_index_on_posts_published_at.sql
V9__normalize_post_status_values.sql
V10__remove_deprecated_meta_columns.sql
V11__ensure_user_security_fields.sql
V12__create_uploaded_files_table.sql
V13__add_performance_indexes.sql
V100__seed_initial_data.sql
R__create_post_statistics_view.sql

src/main/java/com/example/blogapi/
├── BlogApiApplication.java              ← Entry point
│
├── config/
│   ├── CacheConfig.java                 ← Caffeine cache configuration
│   └── OpenApiConfig.java               ← Swagger/OpenAPI configuration
│
├── controller/
│   ├── AuthController.java              ← Register, login, refresh token
│   ├── PostController.java              ← Post CRUD, publish, search, comments
│   ├── UserController.java              ← User profile, avatar upload
│   ├── CategoryController.java          ← Category CRUD
│   ├── TagController.java               ← Tag CRUD
│   ├── FileController.java              ← Serve uploaded files
│   └── AdminController.java             ← User management, cache stats
│
├── dto/
│   ├── CreatePostRequest.java           ← POST /api/posts body
│   ├── UpdatePostRequest.java           ← PUT /api/posts/{id} body
│   ├── PostResponse.java                ← Post data returned to client
│   ├── CreateCommentRequest.java        ← POST /api/posts/{id}/comments body
│   ├── CommentResponse.java             ← Comment data returned to client
│   ├── RegisterRequest.java             ← POST /api/auth/register body
│   ├── LoginRequest.java                ← POST /api/auth/login body
│   ├── AuthResponse.java                ← Login/register response with JWT
│   ├── UserResponse.java                ← User profile data
│   ├── FileUploadResponse.java          ← Upload result metadata
│   └── ErrorResponse.java               ← Consistent error format
│
├── exception/
│   ├── GlobalExceptionHandler.java      ← @ControllerAdvice for all errors
│   ├── ResourceNotFoundException.java   ← 404 errors
│   ├── DuplicateResourceException.java  ← 409 errors
│   └── BadRequestException.java         ← 400 errors
│
├── mapper/
│   ├── PostMapper.java                  ← Post entity ↔ PostResponse
│   ├── CommentMapper.java               ← Comment entity ↔ CommentResponse
│   └── UserMapper.java                  ← User entity ↔ UserResponse
│
├── model/
│   ├── BaseEntity.java                  ← @MappedSuperclass with audit fields
│   ├── User.java                        ← User entity
│   ├── UserProfile.java                 ← User profile entity
│   ├── Post.java                        ← Post entity with relationships
│   ├── Comment.java                     ← Comment entity (self-referencing)
│   ├── Category.java                    ← Category entity
│   ├── Tag.java                         ← Tag entity
│   └── UploadedFile.java                ← File metadata entity
│
├── repository/
│   ├── UserRepository.java              ← findByUsername, findByEmail, exists
│   ├── PostRepository.java              ← findByStatus, searchByKeyword, JOIN FETCH
│   ├── CommentRepository.java           ← findTopLevelByPostId, countByPostId
│   ├── CategoryRepository.java          ← findBySlug
│   ├── TagRepository.java               ← findBySlug
│   └── UploadedFileRepository.java      ← basic CRUD
│
├── security/
│   ├── SecurityConfig.java              ← Filter chain, CORS, endpoint rules
│   ├── JwtTokenProvider.java            ← Generate, validate, parse JWT
│   ├── JwtAuthenticationFilter.java     ← Extract token from every request
│   ├── JwtAuthenticationEntryPoint.java ← Custom 401 response
│   ├── CustomUserDetailsService.java    ← Load user from MariaDB
│   └── PostSecurity.java                ← isAuthor() check for @PreAuthorize
│
├── service/
│   ├── AuthService.java                 ← Register, login, refresh
│   ├── PostService.java                 ← Post business logic + caching
│   ├── CommentService.java              ← Comment business logic
│   ├── UserService.java                 ← User profile management
│   ├── CategoryService.java             ← Category business logic
│   ├── TagService.java                  ← Tag business logic
│   ├── FileStorageService.java          ← Store/load/delete files on disk
│   └── UploadService.java               ← Tie files to posts and users
│
└── validation/
    ├── UniqueUsername.java               ← Custom validator annotation
    └── UniqueUsernameValidator.java      ← Validator implementation

Register:  POST /api/auth/register
             → Validate input (@Valid)
             → Check duplicate username/email
             → Hash password (BCrypt)
             → Save user (ROLE_USER)
             → Return success message

Login:     POST /api/auth/login
             → Validate input (@Valid)
             → AuthenticationManager.authenticate()
               → CustomUserDetailsService.loadUserByUsername()
               → PasswordEncoder.matches()
             → Generate access token (24h)
             → Generate refresh token (7d)
             → Return tokens + user info

Refresh:   POST /api/auth/refresh
             → Validate refresh token
             → Extract username from token
             → Verify user is still active
             → Generate new access token
             → Return new token

Every request:
             → JwtAuthenticationFilter extracts token from Authorization header
             → JwtTokenProvider validates signature + expiration
             → SecurityContext populated with user info
             → @PreAuthorize checks permissions
             → Controller handles request

GET    /api/posts                    ← List posts (paginated, filterable)
GET    /api/posts/{id}               ← Get single post with details
GET    /api/posts/slug/{slug}        ← Get post by URL slug
GET    /api/posts/search?keyword=    ← Search posts
POST   /api/posts                    ← Create post [AUTHOR, ADMIN]
PUT    /api/posts/{id}               ← Update post [author of post, ADMIN]
PATCH  /api/posts/{id}/publish       ← Publish post [author of post, ADMIN]
PATCH  /api/posts/{id}/archive       ← Archive post [ADMIN]
DELETE /api/posts/{id}               ← Delete post [ADMIN]
POST   /api/posts/{id}/cover-image   ← Upload cover image [author of post, ADMIN]
POST   /api/posts/{id}/comments      ← Add comment [authenticated]
GET    /api/posts/{id}/comments      ← List comments (paginated)

GET    /api/categories               ← List all categories
GET    /api/categories/{slug}        ← Get category by slug
POST   /api/categories               ← Create category [ADMIN]
PUT    /api/categories/{id}          ← Update category [ADMIN]
DELETE /api/categories/{id}          ← Delete category [ADMIN]

GET    /api/tags                     ← List all tags
POST   /api/tags                     ← Create tag [ADMIN]
DELETE /api/tags/{id}                ← Delete tag [ADMIN]

GET    /api/users/{id}               ← Get user profile (public info)
PUT    /api/users/me                 ← Update own profile [authenticated]
POST   /api/users/me/avatar          ← Upload avatar [authenticated]

GET    /api/admin/users              ← List all users [ADMIN]
PATCH  /api/admin/users/{id}/role    ← Change user role [ADMIN]
PATCH  /api/admin/users/{id}/deactivate ← Deactivate user [ADMIN]
GET    /api/admin/cache/stats        ← Cache statistics [ADMIN]
DELETE /api/admin/cache              ← Clear all caches [ADMIN]

POST   /api/auth/register            ← Register new user
POST   /api/auth/login               ← Login and get JWT tokens
POST   /api/auth/refresh             ← Refresh access token

GET    /api/files/{*path}            ← Serve uploaded file (public)

GET /api/posts?page=0&size=10&sort=createdAt&direction=desc&status=PUBLISHED

{
  "content": [ ... ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10,
    "sort": { "sorted": true }
  },
  "totalElements": 45,
  "totalPages": 5,
  "first": true,
  "last": false,
  "numberOfElements": 10
}

GET /api/posts/search?keyword=spring+boot&page=0&size=10

// JPQL search (works without special indexes)
@Query("SELECT p FROM Post p WHERE " +
       "LOWER(p.title) LIKE LOWER(CONCAT('%', :keyword, '%')) OR " +
       "LOWER(p.content) LIKE LOWER(CONCAT('%', :keyword, '%'))")
Page<Post> searchByKeyword(@Param("keyword") String keyword, Pageable pageable);

GET /api/posts?status=PUBLISHED              ← Filter by status
GET /api/posts?tag=spring-boot               ← Filter by tag slug
GET /api/posts?category=tutorial             ← Filter by category slug
GET /api/posts?author=alice                  ← Filter by author username

Client                                    Server
  |                                          |
  | POST /api/posts/1/cover-image            |
  | Authorization: Bearer <token>            |
  | Content-Type: multipart/form-data        |
  | [file binary data]                       |
  | ─────────────────────────────────────────>|
  |                                          |
  |    1. Validate file (type, size, name)   |
  |    2. Generate unique filename (UUID)    |
  |    3. Store file on disk                 |
  |    4. Save metadata to uploaded_files    |
  |    5. Link file to post (cover_image_id) |
  |    6. Delete old cover image if exists   |
  |                                          |
  | 201 Created                              |
  | {"fileId":1,"url":"/api/files/..."}      |
  | <─────────────────────────────────────────|

GET /api/files/posts/a1b2c3d4.jpg
  → FileStorageService.loadFileAsResource()
  → Response with Content-Type: image/jpeg
  → Cache-Control: max-age=86400 (browser caches for 24h)

.requestMatchers(HttpMethod.GET, "/api/posts/**").permitAll()
.requestMatchers(HttpMethod.POST, "/api/posts").hasAnyRole("AUTHOR", "ADMIN")
.requestMatchers("/api/admin/**").hasRole("ADMIN")

@PreAuthorize("hasRole('ADMIN') or @postSecurity.isAuthor(#id, authentication.name)")
public PostResponse updatePost(Long id, UpdatePostRequest request) { ... }

./mvnw verify

# Development
docker compose up -d

# Production (with .env secrets)
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

MariaDB: Ready for connections       (5s)
Flyway:  Applied 15 migrations       (3s)
Hibernate: Schema validated          (2s)
Tomcat:  Started on port 8080        (3s)
Application ready                    (Total: ~13s)

☐ Layered architecture: Controller → Service → Repository
☐ Dependencies flow downward only
☐ Controllers handle HTTP, not business logic
☐ Services handle business logic, not HTTP
☐ Repositories handle data access, not business logic
☐ DTOs separate API contract from domain model
☐ Entities never cross the controller boundary
☐ Mappers convert between entities and DTOs

☐ Every relationship uses FetchType.LAZY
☐ @ManyToMany uses Set, not List
☐ Collections are initialized (= new ArrayList<>())
☐ equals() and hashCode() use id only, with null safety
☐ Helper methods keep bidirectional relationships in sync
☐ No @OneToMany for potentially unbounded collections
☐ @JsonIgnore on entity back-references (or use DTOs exclusively)
☐ @PrePersist/@PreUpdate or BaseEntity for timestamps

☐ @Transactional(readOnly = true) at class level
☐ @Transactional on write methods
☐ Guard clauses validate before doing work
☐ Custom exceptions (ResourceNotFoundException, BadRequestException)
☐ Logging at INFO for business events, WARN for unusual cases
☐ Private helper methods for reusable logic
☐ DTO mapping while Hibernate session is open

☐ Passwords hashed with BCrypt (never stored plain text)
☐ JWT secret is 256+ bits, stored as environment variable
☐ CSRF disabled (stateless API)
☐ Sessions disabled (STATELESS)
☐ Public endpoints explicitly marked with permitAll()
☐ @PreAuthorize for method-level authorization
☐ Custom AuthenticationEntryPoint for consistent 401 responses
☐ File uploads validated (type, size, filename)

☐ Flyway manages all schema changes (ddl-auto=validate)
☐ Migrations are immutable once applied
☐ Indexes on columns used in WHERE, ORDER BY, JOIN
☐ Foreign keys enforce referential integrity
☐ utf8mb4 charset for emoji support
☐ No SELECT * — use projections for list pages
☐ N+1 problems fixed with JOIN FETCH or @EntityGraph

☐ Unit tests for service layer business logic
☐ @DataJpaTest for custom repository queries
☐ @WebMvcTest for controller HTTP behavior
☐ Integration tests for critical flows (auth, CRUD)
☐ Tests follow Arrange-Act-Assert pattern
☐ Each test is independent (no shared mutable state)
☐ 80%+ line coverage on service layer

☐ Multi-stage Dockerfile (build + runtime)
☐ Non-root user in Docker container
☐ Docker health check configured
☐ docker-compose.yml with depends_on health checks
☐ Named volumes for data persistence
☐ Secrets in environment variables, not in code
☐ Actuator health endpoint exposed
☐ Swagger UI disabled in production
☐ Logging to file with rotation