Backend engineering.

Snapshot

Package layout

Code is organised by business domain, not by technical layer. Each feature package owns its controllers, services, repositories, DTOs, mappers and tests.

Package catalogue

Layers & responsibilities

Controller surface

36 controllers, all returning ResponseEntity<ApiResponse<T>> (or PagedResponse<T> wrapped in it). Grouped by area:

Conventions

ApiResponse envelope

Every controller method returns the same envelope shape; clients can rely on it:

// 200 OK
{ "success": true, "data": { ... }, "message": null, "timestamp": "2026-05-13T08:21:14Z" }

// 4xx / 5xx
{ "success": false, "data": null,
  "error": { "code": "PROPERTY_NOT_FOUND", "message": "...",
             "fields": { "id": "must not be null" } },
  "timestamp": "..." }

Pagination

@GetMapping
public ResponseEntity<ApiResponse<PagedResponse<PropertyResponse>>> list(
    @ParameterObject PropertyFilter filter,
    @PageableDefault(size = 20, sort = "createdAt", direction = DESC) Pageable pageable
) { ... }

Returned PagedResponse carries content, page, size, totalElements, totalPages, hasNext.

UUID vs slug

• /api/properties/{uuid} — internal/portal use
• /api/properties/slug/{slug} — SEO/public use
• Entities without slugs (User, Payment, Subscription) are UUID-only
• Nested: /api/agencies/{agencyId}/users/{userId}

State machines

ArchUnit rules

Rules live in backend/src/test/java/com/cplk/api/architecture/ArchitectureTest.java. Highlights:

1. Layer dependencies — services↛controllers, repos↛services, controllers↛repos.
2. Controller shape — @RestController, returns ResponseEntity<ApiResponse<T>>; @RequestBody must have @Valid.
3. Repository shape — interfaces extending JpaRepository.
4. Service shape — @Service (exceptions: schedulers, generators, listeners); no HTTP layer access.
5. Injection — constructor injection only via Lombok @RequiredArgsConstructor.
6. Entity table — every @Entity has @Table.
7. Entity inheritance — must extend BaseEntity / ImmutableEntity (whitelist: SystemConfig, projection views, PendingFileKey).
8. Naming — *Controller, *Service, *Repository; DTOs end in Request, Response, Dto.
9. Exception types — no new RuntimeException(msg); use typed app exceptions.
10. Logging — no System.out; SLF4J only.
11. Package cycles — cycle-free except a small whitelist (property↔subscription, payment↔subscription, agency↔user).
12. ApiResponse wrapping — every controller method (exceptions: PayHere webhook returning plain string, bulk import endpoints).
13. Paged endpoints — ApiResponse<PagedResponse<T>>; never raw Page<T>.
14. Entity leakage — controllers must use DTOs (exception: @CurrentUser User).

Testing

Cheatsheet

# build
cd backend && ./gradlew build

# run local profile
cd backend && ./gradlew bootRun --args='--spring.profiles.active=local'

# tests with coverage
ulimit -n 8192 && cd backend && ./gradlew test jacocoTestReport

# enforce coverage gate
cd backend && ./gradlew check

Dependency highlights