[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75THCBHAG0MYHDX0MSJ82NH":3,"skill-same:01M75THCBHAG0MYHDX0MSJ82NH":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":26,"commitSha":27,"skillDirectory":28,"forksCount":29,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":32,"install":33,"resources":46},"01M75THCBHAG0MYHDX0MSJ82NH","backend-patterns",null,"Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.","zeeroiq\u002Fagent-powerhouse","zeeroiq","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F23365484?v=4","01M75TGXCQ9Q7RQMDZGGN6FRBT","Shrikant Vishwakarma","01M75TGXDAECRM3GF3MQV073XD",1,"MIT","https:\u002F\u002Fgithub.com\u002Fzeeroiq\u002Fagent-powerhouse\u002Fblob\u002Fmain\u002Fplugins\u002Fcore\u002Fskills\u002Fbackend-patterns\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: backend-patterns\ndescription: Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.\nmetadata:\n  origin: AgentPowerHouse - APH\n---\n\n# Backend Development Patterns\n\nArchitecture patterns and best practices for scalable Spring Boot applications consumed by React frontends.\n\n---\n\n## When to Activate\n\n- Designing REST API endpoints in Spring Boot\n- Implementing repository, service, or controller layers\n- Optimizing database queries (N+1, indexing, connection pooling)\n- Adding caching (Redis, Spring Cache, HTTP cache headers)\n- Setting up background jobs or async processing\n- Structuring error handling and validation for APIs\n- Building middleware (auth, logging, rate limiting)\n\n---\n\n## API Design Patterns\n\n### RESTful API Structure\n\n```java\n\u002F\u002F Resource-based URLs with Spring MVC\n@RestController\n@RequestMapping(\"\u002Fapi\u002Fv1\u002Fmarkets\")\npublic class MarketController {\n\n    @GetMapping              \u002F\u002F GET \u002Fapi\u002Fv1\u002Fmarkets\n    @GetMapping(\"\u002F{id}\")     \u002F\u002F GET \u002Fapi\u002Fv1\u002Fmarkets\u002F{id}\n    @PostMapping             \u002F\u002F POST \u002Fapi\u002Fv1\u002Fmarkets\n    @PutMapping(\"\u002F{id}\")     \u002F\u002F PUT \u002Fapi\u002Fv1\u002Fmarkets\u002F{id}\n    @PatchMapping(\"\u002F{id}\")   \u002F\u002F PATCH \u002Fapi\u002Fv1\u002Fmarkets\u002F{id}\n    @DeleteMapping(\"\u002F{id}\")  \u002F\u002F DELETE \u002Fapi\u002Fv1\u002Fmarkets\u002F{id}\n}\n\n\u002F\u002F Query parameters for filtering, sorting, pagination\n\u002F\u002F GET \u002Fapi\u002Fv1\u002Fmarkets?status=active&sort=volume,desc&size=20&page=0\n```\n\n### Repository Pattern\n\nSpring Data JPA generates the implementation; you define the interface.\n\n```java\n\u002F\u002F Domain model\n@Entity\n@Table(name = \"markets\")\npublic class Market {\n    @Id @GeneratedValue(strategy = GenerationType.UUID)\n    private UUID id;\n    private String name;\n    private String status;\n    private BigDecimal volume;\n    private LocalDateTime createdAt;\n    \u002F\u002F getters, setters, or use Lombok @Data\n}\n\n\u002F\u002F Repository interface — Spring Data provides the implementation\npublic interface MarketRepository extends JpaRepository\u003CMarket, UUID>,\n        JpaSpecificationExecutor\u003CMarket> {\n\n    List\u003CMarket> findByStatus(String status);\n\n    @Query(\"SELECT m FROM Market m WHERE m.status = :status ORDER BY m.volume DESC\")\n    Page\u003CMarket> findActiveByVolume(@Param(\"status\") String status, Pageable pageable);\n\n    \u002F\u002F Projection query — only the columns you need\n    @Query(\"SELECT m.id AS id, m.name AS name, m.status AS status, m.volume AS volume \" +\n           \"FROM Market m WHERE m.status = :status\")\n    Page\u003CMarketSummary> findSummariesByStatus(@Param(\"status\") String status, Pageable pageable);\n}\n\n\u002F\u002F Projection interface (no extra class needed)\npublic interface MarketSummary {\n    UUID getId();\n    String getName();\n    String getStatus();\n    BigDecimal getVolume();\n}\n```\n\n### Service Layer Pattern\n\n```java\n\u002F\u002F Business logic separated from data access\n@Service\n@RequiredArgsConstructor\n@Transactional(readOnly = true)   \u002F\u002F default: read-only; override per method\npublic class MarketService {\n\n    private final MarketRepository marketRepo;\n    private final EmbeddingService embeddingService;\n\n    public Page\u003CMarketDto> listMarkets(MarketFilters filters, Pageable pageable) {\n        Specification\u003CMarket> spec = Specification\n            .where(MarketSpec.hasStatus(filters.status()))\n            .and(MarketSpec.volumeAtLeast(filters.minVolume()));\n\n        return marketRepo.findAll(spec, pageable).map(MarketDto::from);\n    }\n\n    public List\u003CMarketDto> searchMarkets(String query, int limit) {\n        float[] embedding = embeddingService.embed(query);\n\n        \u002F\u002F Vector search returns IDs + scores\n        List\u003CVectorResult> results = embeddingService.search(embedding, limit);\n        List\u003CUUID> ids = results.stream().map(VectorResult::id).toList();\n\n        \u002F\u002F Batch fetch by IDs (1 query)\n        Map\u003CUUID, Market> marketMap = marketRepo.findAllById(ids)\n            .stream()\n            .collect(Collectors.toMap(Market::getId, Function.identity()));\n\n        \u002F\u002F Reassemble in score order\n        return results.stream()\n            .map(r -> marketMap.get(r.id()))\n            .filter(Objects::nonNull)\n            .map(MarketDto::from)\n            .toList();\n    }\n\n    @Transactional   \u002F\u002F write operation — overrides class-level readOnly\n    public MarketDto create(CreateMarketRequest request) {\n        if (marketRepo.existsByName(request.name())) {\n            throw new DuplicateResourceException(\"Market name already exists: \" + request.name());\n        }\n        Market market = new Market(request.name(), request.status());\n        return MarketDto.from(marketRepo.save(market));\n    }\n}\n```\n\n### Middleware: Filters and Interceptors\n\nSpring has two hook points: `Filter` (servlet level) and `HandlerInterceptor` (MVC level).\n\n```java\n\u002F\u002F Filter — runs for every request, including static resources\n@Component\n@Order(1)\npublic class RequestIdFilter extends OncePerRequestFilter {\n\n    @Override\n    protected void doFilterInternal(HttpServletRequest req,\n            HttpServletResponse res, FilterChain chain)\n            throws ServletException, IOException {\n\n        String requestId = Optional.ofNullable(req.getHeader(\"X-Request-Id\"))\n            .orElse(UUID.randomUUID().toString());\n\n        MDC.put(\"requestId\", requestId);        \u002F\u002F attach to log context\n        res.addHeader(\"X-Request-Id\", requestId);\n\n        try {\n            chain.doFilter(req, res);\n        } finally {\n            MDC.clear();\n        }\n    }\n}\n\n\u002F\u002F HandlerInterceptor — runs only for controller routes\n@Component\n@RequiredArgsConstructor\npublic class AuthInterceptor implements HandlerInterceptor {\n\n    private final JwtService jwtService;\n\n    @Override\n    public boolean preHandle(HttpServletRequest req,\n            HttpServletResponse res, Object handler) {\n\n        if (handler instanceof HandlerMethod hm &&\n                hm.hasMethodAnnotation(PublicEndpoint.class)) {\n            return true;   \u002F\u002F skip auth for @PublicEndpoint methods\n        }\n\n        String token = Optional.ofNullable(req.getHeader(\"Authorization\"))\n            .map(h -> h.replace(\"Bearer \", \"\"))\n            .orElse(null);\n\n        if (token == null) {\n            res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);\n            return false;\n        }\n\n        try {\n            UserPrincipal principal = jwtService.verify(token);\n            req.setAttribute(\"principal\", principal);\n            return true;\n        } catch (JwtException e) {\n            res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);\n            return false;\n        }\n    }\n}\n\n\u002F\u002F Register the interceptor\n@Configuration\n@RequiredArgsConstructor\npublic class WebConfig implements WebMvcConfigurer {\n\n    private final AuthInterceptor authInterceptor;\n\n    @Override\n    public void addInterceptors(InterceptorRegistry registry) {\n        registry.addInterceptor(authInterceptor)\n                .addPathPatterns(\"\u002Fapi\u002F**\")\n                .excludePathPatterns(\"\u002Fapi\u002Fv1\u002Fauth\u002F**\");\n    }\n}\n```\n\n---\n\n## Database Patterns\n\n### Query Optimization — Projections over `select *`\n\n```java\n\u002F\u002F BAD: fetches every column and maps to full entity\nList\u003CMarket> all = marketRepository.findAll();\n\n\u002F\u002F GOOD: projection — only id, name, status, volume reach the JDBC layer\nPage\u003CMarketSummary> summaries = marketRepository\n    .findSummariesByStatus(\"active\", pageable);\n\n\u002F\u002F GOOD: native query with explicit column list when JPQL isn't enough\n@Query(value = \"SELECT id, name, status, volume FROM markets WHERE status = :status\",\n       nativeQuery = true)\nList\u003CMarketProjection> findActiveNative(@Param(\"status\") String status);\n```\n\n### N+1 Query Prevention\n\n```java\n\u002F\u002F BAD: N+1 — one query for markets, then one per market for creator\nList\u003CMarket> markets = marketRepository.findAll();\nmarkets.forEach(m -> m.getCreator().getName()); \u002F\u002F triggers N lazy loads\n\n\u002F\u002F GOOD option 1: JPQL JOIN FETCH\n@Query(\"SELECT m FROM Market m JOIN FETCH m.creator WHERE m.status = :status\")\nList\u003CMarket> findWithCreator(@Param(\"status\") String status);\n\n\u002F\u002F GOOD option 2: @EntityGraph (no query string needed)\n@EntityGraph(attributePaths = {\"creator\", \"category\"})\nList\u003CMarket> findByStatus(String status);\n\n\u002F\u002F GOOD option 3: batch-fetch by IDs (when joining would cause cartesian products)\nList\u003CUUID> ids = marketRepository.findIdsByStatus(\"active\");\nMap\u003CUUID, User> creatorMap = userRepository.findAllById(creatorIds)\n    .stream()\n    .collect(Collectors.toMap(User::getId, Function.identity()));\n```\n\n> **Hibernate tip:** enable `spring.jpa.properties.hibernate.format_sql=true` and `logging.level.org.hibernate.SQL=DEBUG` in development to catch N+1 issues early. Use [Hypersistence Optimizer](https:\u002F\u002Fgithub.com\u002Fvladmihalcea\u002Fhypersistence-optimizer) or [Datasource Proxy](https:\u002F\u002Fgithub.com\u002Fttddyy\u002Fdatasource-proxy) in CI.\n\n### Transaction Pattern\n\n```java\n\u002F\u002F Simple service-level transaction\n@Service\npublic class MarketService {\n\n    @Transactional\n    public MarketWithPosition createMarketWithPosition(\n            CreateMarketRequest marketReq,\n            CreatePositionRequest positionReq) {\n\n        Market market = marketRepository.save(new Market(marketReq));\n        Position position = positionRepository.save(new Position(market, positionReq));\n        \u002F\u002F If either save throws, the whole transaction rolls back automatically\n        return new MarketWithPosition(market, position);\n    }\n}\n\n\u002F\u002F Explicit rollback rules\n@Transactional(rollbackOn = Exception.class,\n               noRollbackOn = OptimisticLockException.class)\npublic void processMarket(UUID id) { \u002F* ... *\u002F }\n\n\u002F\u002F Programmatic transaction (when declarative isn't granular enough)\n@Service\n@RequiredArgsConstructor\npublic class BulkService {\n\n    private final TransactionTemplate txTemplate;\n\n    public void bulkCreate(List\u003CCreateMarketRequest> requests) {\n        requests.forEach(req ->\n            txTemplate.executeWithoutResult(status -> {\n                try {\n                    marketRepository.save(new Market(req));\n                } catch (DataIntegrityViolationException e) {\n                    status.setRollbackOnly();\n                    log.warn(\"Skipped duplicate market: {}\", req.name());\n                }\n            })\n        );\n    }\n}\n```\n\n### Connection Pool Configuration\n\n```yaml\n# application.yml — HikariCP (Spring Boot default)\nspring:\n  datasource:\n    url: jdbc:postgresql:\u002F\u002Flocalhost:5432\u002Fmydb\n    username: ${DB_USERNAME}\n    password: ${DB_PASSWORD}\n    hikari:\n      maximum-pool-size: 20          # tune to (core_count * 2) + effective_spindle_count\n      minimum-idle: 5\n      connection-timeout: 30000      # ms — fail fast rather than queue indefinitely\n      idle-timeout: 600000\n      max-lifetime: 1800000\n      leak-detection-threshold: 60000\n```\n\n---\n\n## Caching Strategies\n\n### Spring Cache Abstraction (Redis-backed)\n\n```java\n\u002F\u002F Enable caching\n@SpringBootApplication\n@EnableCaching\npublic class Application { \u002F* ... *\u002F }\n```\n\n```yaml\n# application.yml\nspring:\n  cache:\n    type: redis\n  data:\n    redis:\n      host: ${REDIS_HOST:localhost}\n      port: 6379\n      timeout: 2000ms\n```\n\n```java\n\u002F\u002F Configure TTLs per cache\n@Configuration\npublic class CacheConfig {\n\n    @Bean\n    public RedisCacheManagerBuilderCustomizer redisCacheCustomizer() {\n        return builder -> builder\n            .withCacheConfiguration(\"markets\",\n                RedisCacheConfiguration.defaultCacheConfig()\n                    .entryTtl(Duration.ofMinutes(5))\n                    .disableCachingNullValues())\n            .withCacheConfiguration(\"market-summaries\",\n                RedisCacheConfiguration.defaultCacheConfig()\n                    .entryTtl(Duration.ofMinutes(10)));\n    }\n}\n\n\u002F\u002F Apply caching at the service layer — not the controller or repository\n@Service\npublic class MarketService {\n\n    @Cacheable(value = \"markets\", key = \"#id\")\n    public MarketDto findById(UUID id) {\n        return marketRepository.findById(id)\n            .map(MarketDto::from)\n            .orElseThrow(() -> new ResourceNotFoundException(\"Market not found: \" + id));\n    }\n\n    @CacheEvict(value = \"markets\", key = \"#id\")\n    @Transactional\n    public MarketDto update(UUID id, UpdateMarketRequest request) {\n        Market market = marketRepository.findById(id)\n            .orElseThrow(() -> new ResourceNotFoundException(\"Market not found: \" + id));\n        market.apply(request);\n        return MarketDto.from(marketRepository.save(market));\n    }\n\n    @CacheEvict(value = \"markets\", allEntries = true)\n    @Transactional\n    public void delete(UUID id) {\n        marketRepository.deleteById(id);\n    }\n}\n```\n\n### Cache-Aside Pattern (Manual \u002F Redis Template)\n\n```java\n@Service\n@RequiredArgsConstructor\npublic class MarketCacheService {\n\n    private final MarketRepository marketRepository;\n    private final RedisTemplate\u003CString, MarketDto> redisTemplate;\n\n    private static final Duration TTL = Duration.ofMinutes(5);\n\n    public MarketDto getMarket(UUID id) {\n        String key = \"market:\" + id;\n\n        \u002F\u002F 1. Try cache\n        MarketDto cached = redisTemplate.opsForValue().get(key);\n        if (cached != null) return cached;\n\n        \u002F\u002F 2. Cache miss — hit the database\n        MarketDto dto = marketRepository.findById(id)\n            .map(MarketDto::from)\n            .orElseThrow(() -> new ResourceNotFoundException(\"Market not found: \" + id));\n\n        \u002F\u002F 3. Populate cache\n        redisTemplate.opsForValue().set(key, dto, TTL);\n        return dto;\n    }\n\n    public void invalidate(UUID id) {\n        redisTemplate.delete(\"market:\" + id);\n    }\n}\n```\n\n---\n\n## Error Handling Patterns\n\n### Custom Exception Hierarchy\n\n```java\n\u002F\u002F Base exception — marks it as a known, operational error\npublic abstract class ApiException extends RuntimeException {\n    private final HttpStatus status;\n    private final String code;\n\n    protected ApiException(HttpStatus status, String code, String message) {\n        super(message);\n        this.status = status;\n        this.code = code;\n    }\n\n    public HttpStatus getStatus() { return status; }\n    public String getCode() { return code; }\n}\n\npublic class ResourceNotFoundException extends ApiException {\n    public ResourceNotFoundException(String message) {\n        super(HttpStatus.NOT_FOUND, \"not_found\", message);\n    }\n}\n\npublic class DuplicateResourceException extends ApiException {\n    public DuplicateResourceException(String message) {\n        super(HttpStatus.CONFLICT, \"conflict\", message);\n    }\n}\n\npublic class ForbiddenException extends ApiException {\n    public ForbiddenException(String message) {\n        super(HttpStatus.FORBIDDEN, \"forbidden\", message);\n    }\n}\n```\n\n### Centralized Error Handler\n\n```java\n@RestControllerAdvice\n@Slf4j\npublic class GlobalExceptionHandler {\n\n    \u002F\u002F Bean Validation failures (@Valid)\n    @ExceptionHandler(MethodArgumentNotValidException.class)\n    public ResponseEntity\u003CErrorResponse> handleValidation(\n            MethodArgumentNotValidException ex) {\n\n        List\u003CFieldError> details = ex.getBindingResult().getFieldErrors().stream()\n            .map(e -> new FieldError(e.getField(), e.getDefaultMessage(), \"invalid_value\"))\n            .toList();\n\n        return ResponseEntity.unprocessableEntity()\n            .body(ErrorResponse.of(\"validation_error\", \"Request validation failed\", details));\n    }\n\n    \u002F\u002F Constraint violations (e.g., @Validated on service methods)\n    @ExceptionHandler(ConstraintViolationException.class)\n    public ResponseEntity\u003CErrorResponse> handleConstraintViolation(\n            ConstraintViolationException ex) {\n\n        List\u003CFieldError> details = ex.getConstraintViolations().stream()\n            .map(v -> new FieldError(\n                v.getPropertyPath().toString(),\n                v.getMessage(),\n                \"constraint_violation\"))\n            .toList();\n\n        return ResponseEntity.unprocessableEntity()\n            .body(ErrorResponse.of(\"validation_error\", \"Constraint violation\", details));\n    }\n\n    \u002F\u002F All operational exceptions\n    @ExceptionHandler(ApiException.class)\n    public ResponseEntity\u003CErrorResponse> handleApiException(ApiException ex) {\n        return ResponseEntity.status(ex.getStatus())\n            .body(ErrorResponse.of(ex.getCode(), ex.getMessage()));\n    }\n\n    \u002F\u002F Malformed JSON \u002F type mismatch\n    @ExceptionHandler(HttpMessageNotReadableException.class)\n    public ResponseEntity\u003CErrorResponse> handleBadJson(\n            HttpMessageNotReadableException ex) {\n        return ResponseEntity.badRequest()\n            .body(ErrorResponse.of(\"invalid_json\", \"Malformed request body\"));\n    }\n\n    \u002F\u002F Optimistic lock conflicts\n    @ExceptionHandler(OptimisticLockingFailureException.class)\n    public ResponseEntity\u003CErrorResponse> handleOptimisticLock(\n            OptimisticLockingFailureException ex) {\n        return ResponseEntity.status(HttpStatus.CONFLICT)\n            .body(ErrorResponse.of(\"conflict\", \"Resource was modified by another request. Retry.\"));\n    }\n\n    \u002F\u002F Catch-all — never expose internal details\n    @ExceptionHandler(Exception.class)\n    public ResponseEntity\u003CErrorResponse> handleUnexpected(Exception ex) {\n        log.error(\"Unexpected error\", ex);\n        return ResponseEntity.internalServerError()\n            .body(ErrorResponse.of(\"internal_error\", \"An unexpected error occurred\"));\n    }\n}\n```\n\n### Retry with Exponential Backoff — Spring Retry\n\n```java\n\u002F\u002F Add spring-retry + spring-aspects to pom.xml, enable on the app class\n@SpringBootApplication\n@EnableRetry\npublic class Application { \u002F* ... *\u002F }\n\n\u002F\u002F Annotate the operation to retry\n@Service\npublic class EmbeddingService {\n\n    @Retryable(\n        retryFor = { HttpServerErrorException.class, ResourceAccessException.class },\n        maxAttempts = 3,\n        backoff = @Backoff(delay = 1000, multiplier = 2)   \u002F\u002F 1s, 2s, 4s\n    )\n    public float[] embed(String text) {\n        return callExternalEmbeddingApi(text);\n    }\n\n    @Recover\n    public float[] embedFallback(Exception ex, String text) {\n        log.error(\"Embedding failed after retries for text: {}\", text, ex);\n        throw new ServiceUnavailableException(\"Embedding service unavailable\");\n    }\n}\n\n\u002F\u002F Programmatic retry (when annotation isn't flexible enough)\n@Bean\npublic RetryTemplate retryTemplate() {\n    return RetryTemplate.builder()\n        .maxAttempts(3)\n        .exponentialBackoff(1000, 2, 8000)\n        .retryOn(HttpServerErrorException.class)\n        .build();\n}\n\n\u002F\u002F Usage\nretryTemplate.execute(ctx -> embeddingClient.embed(text));\n```\n\n---\n\n## Authentication & Authorization\n\n### JWT with Spring Security\n\n```java\n\u002F\u002F JWT service\n@Service\npublic class JwtService {\n\n    @Value(\"${app.jwt.secret}\")\n    private String secret;\n\n    @Value(\"${app.jwt.expiration-ms:3600000}\")\n    private long expirationMs;\n\n    public String generate(UserPrincipal principal) {\n        return Jwts.builder()\n            .subject(principal.id().toString())\n            .claim(\"email\", principal.email())\n            .claim(\"role\", principal.role().name())\n            .issuedAt(new Date())\n            .expiration(new Date(System.currentTimeMillis() + expirationMs))\n            .signWith(getKey())\n            .compact();\n    }\n\n    public UserPrincipal verify(String token) {\n        Claims claims = Jwts.parser()\n            .verifyWith(getKey())\n            .build()\n            .parseSignedClaims(token)\n            .getPayload();\n\n        return new UserPrincipal(\n            UUID.fromString(claims.getSubject()),\n            claims.get(\"email\", String.class),\n            Role.valueOf(claims.get(\"role\", String.class))\n        );\n    }\n\n    private SecretKey getKey() {\n        return Keys.hmacShaKeyFor(Decoders.BASE64.decode(secret));\n    }\n}\n\n\u002F\u002F JWT filter\n@Component\n@RequiredArgsConstructor\npublic class JwtAuthFilter extends OncePerRequestFilter {\n\n    private final JwtService jwtService;\n    private final UserDetailsService userDetailsService;\n\n    @Override\n    protected void doFilterInternal(HttpServletRequest req,\n            HttpServletResponse res, FilterChain chain)\n            throws ServletException, IOException {\n\n        String authHeader = req.getHeader(\"Authorization\");\n        if (authHeader == null || !authHeader.startsWith(\"Bearer \")) {\n            chain.doFilter(req, res);\n            return;\n        }\n\n        try {\n            String token = authHeader.substring(7);\n            UserPrincipal principal = jwtService.verify(token);\n\n            UsernamePasswordAuthenticationToken auth =\n                new UsernamePasswordAuthenticationToken(\n                    principal, null,\n                    List.of(new SimpleGrantedAuthority(\"ROLE_\" + principal.role().name())));\n\n            SecurityContextHolder.getContext().setAuthentication(auth);\n        } catch (JwtException e) {\n            res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);\n            res.getWriter().write(\"{\\\"error\\\":{\\\"code\\\":\\\"invalid_token\\\",\\\"message\\\":\\\"Invalid or expired token\\\"}}\");\n            return;\n        }\n\n        chain.doFilter(req, res);\n    }\n}\n```\n\n### Role-Based Access Control\n\n```java\n\u002F\u002F Enum-based roles\npublic enum Role { ADMIN, MODERATOR, USER }\n\n\u002F\u002F Method security — enable once in a @Configuration\n@Configuration\n@EnableMethodSecurity\npublic class SecurityConfig { \u002F* ... *\u002F }\n\n\u002F\u002F Controller annotations\n@RestController\n@RequestMapping(\"\u002Fapi\u002Fv1\u002Fmarkets\")\npublic class MarketController {\n\n    @GetMapping          \u002F\u002F any authenticated user\n    public Page\u003CMarketDto> list(Pageable pageable) { \u002F* ... *\u002F }\n\n    @PostMapping         \u002F\u002F any authenticated user\n    public ResponseEntity\u003CMarketDto> create(@Valid @RequestBody CreateMarketRequest req) { \u002F* ... *\u002F }\n\n    @DeleteMapping(\"\u002F{id}\")\n    @PreAuthorize(\"hasRole('ADMIN')\")   \u002F\u002F admin only\n    public ResponseEntity\u003CVoid> delete(@PathVariable UUID id) { \u002F* ... *\u002F }\n\n    @PatchMapping(\"\u002F{id}\u002Fresolve\")\n    @PreAuthorize(\"hasAnyRole('ADMIN', 'MODERATOR')\")\n    public ResponseEntity\u003CMarketDto> resolve(@PathVariable UUID id) { \u002F* ... *\u002F }\n}\n\n\u002F\u002F Ownership check in service layer (finer-grained than annotations)\n@Service\npublic class MarketService {\n\n    @Transactional\n    public void delete(UUID marketId, UserPrincipal principal) {\n        Market market = marketRepository.findById(marketId)\n            .orElseThrow(() -> new ResourceNotFoundException(\"Market not found: \" + marketId));\n\n        boolean isOwner = market.getCreatorId().equals(principal.id());\n        boolean isAdmin = principal.role() == Role.ADMIN;\n\n        if (!isOwner && !isAdmin) {\n            throw new ForbiddenException(\"You do not have permission to delete this market\");\n        }\n\n        marketRepository.delete(market);\n    }\n}\n```\n\n---\n\n## Rate Limiting\n\nRate limiting must use a shared store such as Redis, a gateway, or the platform's native limiter. Do not use per-process in-memory counters for production: they reset on deploy, split across replicas, and fail open in multi-instance or serverless environments.\n\n```java\n\u002F\u002F Bucket4j with Redis (see api-design doc for full implementation)\n@Component\n@RequiredArgsConstructor\npublic class RateLimitFilter extends OncePerRequestFilter {\n\n    private final BucketRepository bucketRepository;  \u002F\u002F Redis-backed\n\n    private static final Map\u003CString, BandwidthDefinition> TIERS = Map.of(\n        \"anonymous\",     Bandwidth.classic(30,  Refill.intervally(30,  Duration.ofMinutes(1))),\n        \"authenticated\", Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1))),\n        \"premium\",       Bandwidth.classic(1000,Refill.intervally(1000,Duration.ofMinutes(1)))\n    );\n\n    @Override\n    protected void doFilterInternal(HttpServletRequest req,\n            HttpServletResponse res, FilterChain chain)\n            throws ServletException, IOException {\n\n        String tier = resolveTier(req);\n        String key  = resolveKey(req, tier);\n        Bucket bucket = bucketRepository.getOrCreate(key, TIERS.get(tier));\n\n        ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(1);\n        res.addHeader(\"X-RateLimit-Remaining\", String.valueOf(probe.getRemainingTokens()));\n\n        if (!probe.isConsumed()) {\n            res.setStatus(429);\n            res.addHeader(\"Retry-After\", \"60\");\n            return;\n        }\n        chain.doFilter(req, res);\n    }\n\n    private String resolveTier(HttpServletRequest req) {\n        if (req.getHeader(\"X-API-Key\") != null) return \"premium\";\n        if (SecurityContextHolder.getContext().getAuthentication() != null) return \"authenticated\";\n        return \"anonymous\";\n    }\n}\n```\n\n---\n\n## Background Jobs & Async Processing\n\n### Spring @Async (fire-and-forget)\n\n```java\n@SpringBootApplication\n@EnableAsync\npublic class Application { \u002F* ... *\u002F }\n\n\u002F\u002F Thread pool configuration\n@Configuration\npublic class AsyncConfig {\n\n    @Bean(\"taskExecutor\")\n    public Executor taskExecutor() {\n        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();\n        executor.setCorePoolSize(4);\n        executor.setMaxPoolSize(10);\n        executor.setQueueCapacity(100);\n        executor.setThreadNamePrefix(\"async-\");\n        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());\n        executor.initialize();\n        return executor;\n    }\n}\n\n\u002F\u002F Async service method\n@Service\n@Slf4j\npublic class IndexingService {\n\n    @Async(\"taskExecutor\")\n    public CompletableFuture\u003CVoid> indexMarket(UUID marketId) {\n        try {\n            Market market = marketRepository.findById(marketId)\n                .orElseThrow(() -> new ResourceNotFoundException(\"Market not found\"));\n            vectorStore.upsert(market.getId(), embeddingService.embed(market.toText()));\n            log.info(\"Indexed market {}\", marketId);\n        } catch (Exception e) {\n            log.error(\"Failed to index market {}\", marketId, e);\n        }\n        return CompletableFuture.completedFuture(null);\n    }\n}\n\n\u002F\u002F Controller: respond immediately, index in background\n@PostMapping\npublic ResponseEntity\u003CMarketDto> create(@Valid @RequestBody CreateMarketRequest req) {\n    MarketDto created = marketService.create(req);\n    indexingService.indexMarket(created.id());   \u002F\u002F non-blocking\n    return ResponseEntity.status(HttpStatus.CREATED).body(created);\n}\n```\n\n### Scheduled Jobs — Spring @Scheduled\n\n```java\n@Component\n@Slf4j\n@RequiredArgsConstructor\npublic class MarketSyncJob {\n\n    private final MarketSyncService syncService;\n\n    @Scheduled(cron = \"0 0 * * * *\")         \u002F\u002F top of every hour\n    public void syncActiveMarkets() {\n        log.info(\"Starting market sync\");\n        try {\n            int synced = syncService.syncAll();\n            log.info(\"Synced {} markets\", synced);\n        } catch (Exception e) {\n            log.error(\"Market sync failed\", e);\n        }\n    }\n\n    @Scheduled(fixedDelay = 30_000, initialDelay = 10_000)  \u002F\u002F every 30s\n    public void processQueue() {\n        syncService.drainQueue();\n    }\n}\n\n\u002F\u002F Enable scheduling\n@SpringBootApplication\n@EnableScheduling\npublic class Application { \u002F* ... *\u002F }\n```\n\n### Durable Queues with Spring Events + Outbox Pattern\n\nFor operations that must survive restarts, use a transactional outbox instead of `@Async`:\n\n```java\n\u002F\u002F 1. Save the job atomically with the triggering transaction\n@Transactional\npublic MarketDto create(CreateMarketRequest request) {\n    Market market = marketRepository.save(new Market(request));\n    outboxRepository.save(new OutboxEvent(\"market.created\", market.getId().toString()));\n    return MarketDto.from(market);\n}\n\n\u002F\u002F 2. Poll the outbox table and dispatch\n@Scheduled(fixedDelay = 5_000)\n@Transactional\npublic void processOutbox() {\n    List\u003COutboxEvent> pending = outboxRepository.findPendingWithLock(10);\n    pending.forEach(event -> {\n        try {\n            dispatch(event);\n            event.markProcessed();\n        } catch (Exception e) {\n            event.incrementRetries();\n            log.error(\"Failed to dispatch event {}\", event.getId(), e);\n        }\n    });\n}\n```\n\n---\n\n## Logging & Monitoring\n\n### Structured Logging with SLF4J + Logback + MDC\n\n```java\n\u002F\u002F logback-spring.xml — JSON output for log aggregators (Datadog, Loki, CloudWatch)\n\u002F\u002F Use logstash-logback-encoder:\n\u002F\u002F \u003Cdependency>\n\u002F\u002F   \u003CgroupId>net.logstash.logback\u003C\u002FgroupId>\n\u002F\u002F   \u003CartifactId>logstash-logback-encoder\u003C\u002FartifactId>\n\u002F\u002F \u003C\u002Fdependency>\n```\n\n```xml\n\u003C!-- logback-spring.xml -->\n\u003Cappender name=\"JSON\" class=\"ch.qos.logback.core.ConsoleAppender\">\n  \u003Cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\">\n    \u003CincludeMdcKeyName>requestId\u003C\u002FincludeMdcKeyName>\n    \u003CincludeMdcKeyName>userId\u003C\u002FincludeMdcKeyName>\n    \u003CincludeMdcKeyName>traceId\u003C\u002FincludeMdcKeyName>\n  \u003C\u002Fencoder>\n\u003C\u002Fappender>\n\n\u003Croot level=\"INFO\">\n  \u003Cappender-ref ref=\"JSON\"\u002F>\n\u003C\u002Froot>\n```\n\n```java\n\u002F\u002F Request filter — populate MDC for every request\n@Component\n@Order(Ordered.HIGHEST_PRECEDENCE)\npublic class MdcFilter extends OncePerRequestFilter {\n\n    @Override\n    protected void doFilterInternal(HttpServletRequest req,\n            HttpServletResponse res, FilterChain chain)\n            throws ServletException, IOException {\n\n        String requestId = Optional.ofNullable(req.getHeader(\"X-Request-Id\"))\n            .orElse(UUID.randomUUID().toString());\n\n        MDC.put(\"requestId\", requestId);\n        MDC.put(\"method\", req.getMethod());\n        MDC.put(\"path\", req.getRequestURI());\n\n        \u002F\u002F If JWT is already parsed, attach userId\n        Authentication auth = SecurityContextHolder.getContext().getAuthentication();\n        if (auth != null && auth.getPrincipal() instanceof UserPrincipal p) {\n            MDC.put(\"userId\", p.id().toString());\n        }\n\n        try {\n            chain.doFilter(req, res);\n        } finally {\n            MDC.clear();   \u002F\u002F critical — thread pool reuse means stale MDC leaks\n        }\n    }\n}\n\n\u002F\u002F Service-level logging — MDC fields are added automatically\n@Service\n@Slf4j\npublic class MarketService {\n\n    public MarketDto findById(UUID id) {\n        log.info(\"Fetching market\");   \u002F\u002F requestId, userId added by MDC filter\n        return marketRepository.findById(id)\n            .map(MarketDto::from)\n            .orElseThrow(() -> {\n                log.warn(\"Market not found: {}\", id);\n                return new ResourceNotFoundException(\"Market not found: \" + id);\n            });\n    }\n}\n```\n\n### Actuator & Health Checks\n\n```yaml\n# application.yml\nmanagement:\n  endpoints:\n    web:\n      exposure:\n        include: health, info, metrics, prometheus\n      base-path: \u002Finternal\n  endpoint:\n    health:\n      show-details: when-authorized\n  metrics:\n    tags:\n      application: ${spring.application.name}\n```\n\n```java\n\u002F\u002F Custom health indicator\n@Component\n@RequiredArgsConstructor\npublic class VectorStoreHealthIndicator implements HealthIndicator {\n\n    private final VectorStore vectorStore;\n\n    @Override\n    public Health health() {\n        try {\n            vectorStore.ping();\n            return Health.up().withDetail(\"vectorStore\", \"reachable\").build();\n        } catch (Exception e) {\n            return Health.down().withDetail(\"vectorStore\", e.getMessage()).build();\n        }\n    }\n}\n```\n\n---\n\n## React: Consuming Backend Patterns\n\n### Retry and Error Boundary\n\n```tsx\n\u002F\u002F src\u002Fcomponents\u002FAsyncBoundary.tsx — wraps TanStack Query errors\nimport { QueryErrorResetBoundary } from \"@tanstack\u002Freact-query\";\nimport { ErrorBoundary } from \"react-error-boundary\";\n\nexport function AsyncBoundary({ children }: { children: React.ReactNode }) {\n  return (\n    \u003CQueryErrorResetBoundary>\n      {({ reset }) => (\n        \u003CErrorBoundary\n          onReset={reset}\n          fallbackRender={({ error, resetErrorBoundary }) => (\n            \u003Cdiv role=\"alert\">\n              \u003Cp>Something went wrong: {error.message}\u003C\u002Fp>\n              \u003Cbutton onClick={resetErrorBoundary}>Retry\u003C\u002Fbutton>\n            \u003C\u002Fdiv>\n          )}\n        >\n          {children}\n        \u003C\u002FErrorBoundary>\n      )}\n    \u003C\u002FQueryErrorResetBoundary>\n  );\n}\n```\n\n### Optimistic Updates\n\n```tsx\n\u002F\u002F src\u002Fhooks\u002FuseMarkets.ts\nexport function useDeleteMarket() {\n  const queryClient = useQueryClient();\n\n  return useMutation({\n    mutationFn: marketsApi.delete,\n\n    onMutate: async (id: string) => {\n      await queryClient.cancelQueries({ queryKey: marketKeys.list() });\n      const previous = queryClient.getQueryData(marketKeys.list());\n\n      \u002F\u002F Optimistically remove from list\n      queryClient.setQueryData(marketKeys.list(), (old: PagedResponse\u003CMarketDto>) => ({\n        ...old,\n        data: old.data.filter((m) => m.id !== id),\n      }));\n\n      return { previous };\n    },\n\n    onError: (_err, _id, context) => {\n      \u002F\u002F Rollback on failure\n      queryClient.setQueryData(marketKeys.list(), context?.previous);\n    },\n\n    onSettled: () => {\n      queryClient.invalidateQueries({ queryKey: marketKeys.list() });\n    },\n  });\n}\n```\n\n### Background Refetching and Polling\n\n```tsx\n\u002F\u002F Poll for a resource until its status changes (e.g., async job completion)\nexport function useMarket(id: string) {\n  return useQuery({\n    queryKey: marketKeys.detail(id),\n    queryFn: () => marketsApi.getById(id),\n    refetchInterval: (query) => {\n      const status = query.state.data?.status;\n      \u002F\u002F Stop polling once the job finishes\n      return status === \"indexing\" ? 3000 : false;\n    },\n  });\n}\n```\n\n---\n\n## Architecture Layering Reference\n\n```\nController        — HTTP binding (@RestController, @Valid, ResponseEntity)\n     ↓\nService           — Business logic, @Transactional, @Cacheable\n     ↓\nRepository        — Data access (JpaRepository, @Query, Specification)\n     ↓\nDatabase          — PostgreSQL \u002F Redis \u002F Vector store\n```\n\n**Rules:**\n- Controllers never call repositories directly — only services.\n- Services own transactions; repositories are transaction-aware but don't define them.\n- DTOs cross the controller ↔ service boundary; domain entities stay in service ↔ repository.\n- Never expose JPA entities in API responses — mapper to DTO first.\n\n---\n\n## Checklist\n\nBefore shipping a new feature:\n\n- [ ] Controller delegates to service — no business logic in `@RestController`\n- [ ] `@Transactional(readOnly = true)` on service class, `@Transactional` on mutating methods only\n- [ ] N+1 queries eliminated — verified with SQL logging enabled\n- [ ] Projections used for list endpoints instead of full entities\n- [ ] `@Valid` on all `@RequestBody` parameters\n- [ ] `@RestControllerAdvice` handles all exception types\n- [ ] `@Cacheable` \u002F `@CacheEvict` applied at service layer, not controller\n- [ ] Async jobs (`@Async`) don't swallow exceptions — use `CompletableFuture` or a recovery method\n- [ ] MDC populated per-request and cleared in `finally`\n- [ ] No JPA entities serialized to JSON — always map to DTOs\n- [ ] React query keys follow `[resource, action, params]` structure\n- [ ] Optimistic updates with rollback for destructive mutations\n- [ ] `AsyncBoundary` wraps all data-fetching subtrees","# Backend Development Patterns\n\nArchitecture patterns and best practices for scalable Spring Boot applications consumed by React frontends.\n\n---\n\n## When to Activate\n\n- Designing REST API endpoints in Spring Boot\n- Implementing repository, service, or controller layers\n- Optimizing database queries (N+1, indexing, connection pooling)\n- Adding caching (Redis, Spring Cache, HTTP cache headers)\n- Setting up background jobs or async processing\n- Structuring error handling and validation for APIs\n- Building middleware (auth, logging, rate limiting)\n\n---\n\n## API Design Patterns\n\n### RESTful API Structure\n\n```java\n\u002F\u002F Resource-based URLs with Spring MVC\n@RestController\n@RequestMapping(\"\u002Fapi\u002Fv1\u002Fmarkets\")\npublic class MarketController {\n\n    @GetMapping              \u002F\u002F GET \u002Fapi\u002Fv1\u002Fmarkets\n    @GetMapping(\"\u002F{id}\")     \u002F\u002F GET \u002Fapi\u002Fv1\u002Fmarkets\u002F{id}\n    @PostMapping             \u002F\u002F POST \u002Fapi\u002Fv1\u002Fmarkets\n    @PutMapping(\"\u002F{id}\")     \u002F\u002F PUT \u002Fapi\u002Fv1\u002Fmarkets\u002F{id}\n    @PatchMapping(\"\u002F{id}\")   \u002F\u002F PATCH \u002Fapi\u002Fv1\u002Fmarkets\u002F{id}\n    @DeleteMapping(\"\u002F{id}\")  \u002F\u002F DELETE \u002Fapi\u002Fv1\u002Fmarkets\u002F{id}\n}\n\n\u002F\u002F Query parameters for filtering, sorting, pagination\n\u002F\u002F GET \u002Fapi\u002Fv1\u002Fmarkets?status=active&sort=volume,desc&size=20&page=0\n```\n\n### Repository Pattern\n\nSpring Data JPA generates the implementation; you define the interface.\n\n```java\n\u002F\u002F Domain model\n@Entity\n@Table(name = \"markets\")\npublic class Market {\n    @Id @GeneratedValue(strategy = GenerationType.UUID)\n    private UUID id;\n    private String name;\n    private String status;\n    private BigDecimal volume;\n    private LocalDateTime createdAt;\n    \u002F\u002F getters, setters, or use Lombok @Data\n}\n\n\u002F\u002F Repository interface — Spring Data provides the implementation\npublic interface MarketRepository extends JpaRepository\u003CMarket, UUID>,\n        JpaSpecificationExecutor\u003CMarket> {\n\n    List\u003CMarket> findByStatus(String status);\n\n    @Query(\"SELECT m FROM Market m WHERE m.status = :status ORDER BY m.volume DESC\")\n    Page\u003CMarket> findActiveByVolume(@Param(\"status\") String status, Pageable pageable);\n\n    \u002F\u002F Projection query — only the columns you need\n    @Query(\"SELECT m.id AS id, m.name AS name, m.status AS status, m.volume AS volume \" +\n           \"FROM Market m WHERE m.status = :status\")\n    Page\u003CMarketSummary> findSummariesByStatus(@Param(\"status\") String status, Pageable pageable);\n}\n\n\u002F\u002F Projection interface (no extra class needed)\npublic interface MarketSummary {\n    UUID getId();\n    String getName();\n    String getStatus();\n    BigDecimal getVolume();\n}\n```\n\n### Service Layer Pattern\n\n```java\n\u002F\u002F Business logic separated from data access\n@Service\n@RequiredArgsConstructor\n@Transactional(readOnly = true)   \u002F\u002F default: read-only; override per method\npublic class MarketService {\n\n    private final MarketRepository marketRepo;\n    private final EmbeddingService embeddingService;\n\n    public Page\u003CMarketDto> listMarkets(MarketFilters filters, Pageable pageable) {\n        Specification\u003CMarket> spec = Specification\n            .where(MarketSpec.hasStatus(filters.status()))\n            .and(MarketSpec.volumeAtLeast(filters.minVolume()));\n\n        return marketRepo.findAll(spec, pageable).map(MarketDto::from);\n    }\n\n    public List\u003CMarketDto> searchMarkets(String query, int limit) {\n        float[] embedding = embeddingService.embed(query);\n\n        \u002F\u002F Vector search returns IDs + scores\n        List\u003CVectorResult> results = embeddingService.search(embedding, limit);\n        List\u003CUUID> ids = results.stream().map(VectorResult::id).toList();\n\n        \u002F\u002F Batch fetch by IDs (1 query)\n        Map\u003CUUID, Market> marketMap = marketRepo.findAllById(ids)\n            .stream()\n            .collect(Collectors.toMap(Market::getId, Function.identity()));\n\n        \u002F\u002F Reassemble in score order\n        return results.stream()\n            .map(r -> marketMap.get(r.id()))\n            .filter(Objects::nonNull)\n            .map(MarketDto::from)\n            .toList();\n    }\n\n    @Transactional   \u002F\u002F write operation — overrides class-level readOnly\n    public MarketDto create(CreateMarketRequest request) {\n        if (marketRepo.existsByName(request.name())) {\n            throw new DuplicateResourceException(\"Market name already exists: \" + request.name());\n        }\n        Market market = new Market(request.name(), request.status());\n        return MarketDto.from(marketRepo.save(market));\n    }\n}\n```\n\n### Middleware: Filters and Interceptors\n\nSpring has two hook points: `Filter` (servlet level) and `HandlerInterceptor` (MVC level).\n\n```java\n\u002F\u002F Filter — runs for every request, including static resources\n@Component\n@Order(1)\npublic class RequestIdFilter extends OncePerRequestFilter {\n\n    @Override\n    protected void doFilterInternal(HttpServletRequest req,\n            HttpServletResponse res, FilterChain chain)\n            throws ServletException, IOException {\n\n        String requestId = Optional.ofNullable(req.getHeader(\"X-Request-Id\"))\n            .orElse(UUID.randomUUID().toString());\n\n        MDC.put(\"requestId\", requestId);        \u002F\u002F attach to log context\n        res.addHeader(\"X-Request-Id\", requestId);\n\n        try {\n            chain.doFilter(req, res);\n        } finally {\n            MDC.clear();\n        }\n    }\n}\n\n\u002F\u002F HandlerInterceptor — runs only for controller routes\n@Component\n@RequiredArgsConstructor\npublic class AuthInterceptor implements HandlerInterceptor {\n\n    private final JwtService jwtService;\n\n    @Override\n    public boolean preHandle(HttpServletRequest req,\n            HttpServletResponse res, Object handler) {\n\n        if (handler instanceof HandlerMethod hm &&\n                hm.hasMethodAnnotation(PublicEndpoint.class)) {\n            return true;   \u002F\u002F skip auth for @PublicEndpoint methods\n        }\n\n        String token = Optional.ofNullable(req.getHeader(\"Authorization\"))\n            .map(h -> h.replace(\"Bearer \", \"\"))\n            .orElse(null);\n\n        if (token == null) {\n            res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);\n            return false;\n        }\n\n        try {\n            UserPrincipal principal = jwtService.verify(token);\n            req.setAttribute(\"principal\", principal);\n            return true;\n        } catch (JwtException e) {\n            res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);\n            return false;\n        }\n    }\n}\n\n\u002F\u002F Register the interceptor\n@Configuration\n@RequiredArgsConstructor\npublic class WebConfig implements WebMvcConfigurer {\n\n    private final AuthInterceptor authInterceptor;\n\n    @Override\n    public void addInterceptors(InterceptorRegistry registry) {\n        registry.addInterceptor(authInterceptor)\n                .addPathPatterns(\"\u002Fapi\u002F**\")\n                .excludePathPatterns(\"\u002Fapi\u002Fv1\u002Fauth\u002F**\");\n    }\n}\n```\n\n---\n\n## Database Patterns\n\n### Query Optimization — Projections over `select *`\n\n```java\n\u002F\u002F BAD: fetches every column and maps to full entity\nList\u003CMarket> all = marketRepository.findAll();\n\n\u002F\u002F GOOD: projection — only id, name, status, volume reach the JDBC layer\nPage\u003CMarketSummary> summaries = marketRepository\n    .findSummariesByStatus(\"active\", pageable);\n\n\u002F\u002F GOOD: native query with explicit column list when JPQL isn't enough\n@Query(value = \"SELECT id, name, status, volume FROM markets WHERE status = :status\",\n       nativeQuery = true)\nList\u003CMarketProjection> findActiveNative(@Param(\"status\") String status);\n```\n\n### N+1 Query Prevention\n\n```java\n\u002F\u002F BAD: N+1 — one query for markets, then one per market for creator\nList\u003CMarket> markets = marketRepository.findAll();\nmarkets.forEach(m -> m.getCreator().getName()); \u002F\u002F triggers N lazy loads\n\n\u002F\u002F GOOD option 1: JPQL JOIN FETCH\n@Query(\"SELECT m FROM Market m JOIN FETCH m.creator WHERE m.status = :status\")\nList\u003CMarket> findWithCreator(@Param(\"status\") String status);\n\n\u002F\u002F GOOD option 2: @EntityGraph (no query string needed)\n@EntityGraph(attributePaths = {\"creator\", \"category\"})\nList\u003CMarket> findByStatus(String status);\n\n\u002F\u002F GOOD option 3: batch-fetch by IDs (when joining would cause cartesian products)\nList\u003CUUID> ids = marketRepository.findIdsByStatus(\"active\");\nMap\u003CUUID, User> creatorMap = userRepository.findAllById(creatorIds)\n    .stream()\n    .collect(Collectors.toMap(User::getId, Function.identity()));\n```\n\n> **Hibernate tip:** enable `spring.jpa.properties.hibernate.format_sql=true` and `logging.level.org.hibernate.SQL=DEBUG` in development to catch N+1 issues early. Use [Hypersistence Optimizer](https:\u002F\u002Fgithub.com\u002Fvladmihalcea\u002Fhypersistence-optimizer) or [Datasource Proxy](https:\u002F\u002Fgithub.com\u002Fttddyy\u002Fdatasource-proxy) in CI.\n\n### Transaction Pattern\n\n```java\n\u002F\u002F Simple service-level transaction\n@Service\npublic class MarketService {\n\n    @Transactional\n    public MarketWithPosition createMarketWithPosition(\n            CreateMarketRequest marketReq,\n            CreatePositionRequest positionReq) {\n\n        Market market = marketRepository.save(new Market(marketReq));\n        Position position = positionRepository.save(new Position(market, positionReq));\n        \u002F\u002F If either save throws, the whole transaction rolls back automatically\n        return new MarketWithPosition(market, position);\n    }\n}\n\n\u002F\u002F Explicit rollback rules\n@Transactional(rollbackOn = Exception.class,\n               noRollbackOn = OptimisticLockException.class)\npublic void processMarket(UUID id) { \u002F* ... *\u002F }\n\n\u002F\u002F Programmatic transaction (when declarative isn't granular enough)\n@Service\n@RequiredArgsConstructor\npublic class BulkService {\n\n    private final TransactionTemplate txTemplate;\n\n    public void bulkCreate(List\u003CCreateMarketRequest> requests) {\n        requests.forEach(req ->\n            txTemplate.executeWithoutResult(status -> {\n                try {\n                    marketRepository.save(new Market(req));\n                } catch (DataIntegrityViolationException e) {\n                    status.setRollbackOnly();\n                    log.warn(\"Skipped duplicate market: {}\", req.name());\n                }\n            })\n        );\n    }\n}\n```\n\n### Connection Pool Configuration\n\n```yaml\n# application.yml — HikariCP (Spring Boot default)\nspring:\n  datasource:\n    url: jdbc:postgresql:\u002F\u002Flocalhost:5432\u002Fmydb\n    username: ${DB_USERNAME}\n    password: ${DB_PASSWORD}\n    hikari:\n      maximum-pool-size: 20          # tune to (core_count * 2) + effective_spindle_count\n      minimum-idle: 5\n      connection-timeout: 30000      # ms — fail fast rather than queue indefinitely\n      idle-timeout: 600000\n      max-lifetime: 1800000\n      leak-detection-threshold: 60000\n```\n\n---\n\n## Caching Strategies\n\n### Spring Cache Abstraction (Redis-backed)\n\n```java\n\u002F\u002F Enable caching\n@SpringBootApplication\n@EnableCaching\npublic class Application { \u002F* ... *\u002F }\n```\n\n```yaml\n# application.yml\nspring:\n  cache:\n    type: redis\n  data:\n    redis:\n      host: ${REDIS_HOST:localhost}\n      port: 6379\n      timeout: 2000ms\n```\n\n```java\n\u002F\u002F Configure TTLs per cache\n@Configuration\npublic class CacheConfig {\n\n    @Bean\n    public RedisCacheManagerBuilderCustomizer redisCacheCustomizer() {\n        return builder -> builder\n            .withCacheConfiguration(\"markets\",\n                RedisCacheConfiguration.defaultCacheConfig()\n                    .entryTtl(Duration.ofMinutes(5))\n                    .disableCachingNullValues())\n            .withCacheConfiguration(\"market-summaries\",\n                RedisCacheConfiguration.defaultCacheConfig()\n                    .entryTtl(Duration.ofMinutes(10)));\n    }\n}\n\n\u002F\u002F Apply caching at the service layer — not the controller or repository\n@Service\npublic class MarketService {\n\n    @Cacheable(value = \"markets\", key = \"#id\")\n    public MarketDto findById(UUID id) {\n        return marketRepository.findById(id)\n            .map(MarketDto::from)\n            .orElseThrow(() -> new ResourceNotFoundException(\"Market not found: \" + id));\n    }\n\n    @CacheEvict(value = \"markets\", key = \"#id\")\n    @Transactional\n    public MarketDto update(UUID id, UpdateMarketRequest request) {\n        Market market = marketRepository.findById(id)\n            .orElseThrow(() -> new ResourceNotFoundException(\"Market not found: \" + id));\n        market.apply(request);\n        return MarketDto.from(marketRepository.save(market));\n    }\n\n    @CacheEvict(value = \"markets\", allEntries = true)\n    @Transactional\n    public void delete(UUID id) {\n        marketRepository.deleteById(id);\n    }\n}\n```\n\n### Cache-Aside Pattern (Manual \u002F Redis Template)\n\n```java\n@Service\n@RequiredArgsConstructor\npublic class MarketCacheService {\n\n    private final MarketRepository marketRepository;\n    private final RedisTemplate\u003CString, MarketDto> redisTemplate;\n\n    private static final Duration TTL = Duration.ofMinutes(5);\n\n    public MarketDto getMarket(UUID id) {\n        String key = \"market:\" + id;\n\n        \u002F\u002F 1. Try cache\n        MarketDto cached = redisTemplate.opsForValue().get(key);\n        if (cached != null) return cached;\n\n        \u002F\u002F 2. Cache miss — hit the database\n        MarketDto dto = marketRepository.findById(id)\n            .map(MarketDto::from)\n            .orElseThrow(() -> new ResourceNotFoundException(\"Market not found: \" + id));\n\n        \u002F\u002F 3. Populate cache\n        redisTemplate.opsForValue().set(key, dto, TTL);\n        return dto;\n    }\n\n    public void invalidate(UUID id) {\n        redisTemplate.delete(\"market:\" + id);\n    }\n}\n```\n\n---\n\n## Error Handling Patterns\n\n### Custom Exception Hierarchy\n\n```java\n\u002F\u002F Base exception — marks it as a known, operational error\npublic abstract class ApiException extends RuntimeException {\n    private final HttpStatus status;\n    private final String code;\n\n    protected ApiException(HttpStatus status, String code, String message) {\n        super(message);\n        this.status = status;\n        this.code = code;\n    }\n\n    public HttpStatus getStatus() { return status; }\n    public String getCode() { return code; }\n}\n\npublic class ResourceNotFoundException extends ApiException {\n    public ResourceNotFoundException(String message) {\n        super(HttpStatus.NOT_FOUND, \"not_found\", message);\n    }\n}\n\npublic class DuplicateResourceException extends ApiException {\n    public DuplicateResourceException(String message) {\n        super(HttpStatus.CONFLICT, \"conflict\", message);\n    }\n}\n\npublic class ForbiddenException extends ApiException {\n    public ForbiddenException(String message) {\n        super(HttpStatus.FORBIDDEN, \"forbidden\", message);\n    }\n}\n```\n\n### Centralized Error Handler\n\n```java\n@RestControllerAdvice\n@Slf4j\npublic class GlobalExceptionHandler {\n\n    \u002F\u002F Bean Validation failures (@Valid)\n    @ExceptionHandler(MethodArgumentNotValidException.class)\n    public ResponseEntity\u003CErrorResponse> handleValidation(\n            MethodArgumentNotValidException ex) {\n\n        List\u003CFieldError> details = ex.getBindingResult().getFieldErrors().stream()\n            .map(e -> new FieldError(e.getField(), e.getDefaultMessage(), \"invalid_value\"))\n            .toList();\n\n        return ResponseEntity.unprocessableEntity()\n            .body(ErrorResponse.of(\"validation_error\", \"Request validation failed\", details));\n    }\n\n    \u002F\u002F Constraint violations (e.g., @Validated on service methods)\n    @ExceptionHandler(ConstraintViolationException.class)\n    public ResponseEntity\u003CErrorResponse> handleConstraintViolation(\n            ConstraintViolationException ex) {\n\n        List\u003CFieldError> details = ex.getConstraintViolations().stream()\n            .map(v -> new FieldError(\n                v.getPropertyPath().toString(),\n                v.getMessage(),\n                \"constraint_violation\"))\n            .toList();\n\n        return ResponseEntity.unprocessableEntity()\n            .body(ErrorResponse.of(\"validation_error\", \"Constraint violation\", details));\n    }\n\n    \u002F\u002F All operational exceptions\n    @ExceptionHandler(ApiException.class)\n    public ResponseEntity\u003CErrorResponse> handleApiException(ApiException ex) {\n        return ResponseEntity.status(ex.getStatus())\n            .body(ErrorResponse.of(ex.getCode(), ex.getMessage()));\n    }\n\n    \u002F\u002F Malformed JSON \u002F type mismatch\n    @ExceptionHandler(HttpMessageNotReadableException.class)\n    public ResponseEntity\u003CErrorResponse> handleBadJson(\n            HttpMessageNotReadableException ex) {\n        return ResponseEntity.badRequest()\n            .body(ErrorResponse.of(\"invalid_json\", \"Malformed request body\"));\n    }\n\n    \u002F\u002F Optimistic lock conflicts\n    @ExceptionHandler(OptimisticLockingFailureException.class)\n    public ResponseEntity\u003CErrorResponse> handleOptimisticLock(\n            OptimisticLockingFailureException ex) {\n        return ResponseEntity.status(HttpStatus.CONFLICT)\n            .body(ErrorResponse.of(\"conflict\", \"Resource was modified by another request. Retry.\"));\n    }\n\n    \u002F\u002F Catch-all — never expose internal details\n    @ExceptionHandler(Exception.class)\n    public ResponseEntity\u003CErrorResponse> handleUnexpected(Exception ex) {\n        log.error(\"Unexpected error\", ex);\n        return ResponseEntity.internalServerError()\n            .body(ErrorResponse.of(\"internal_error\", \"An unexpected error occurred\"));\n    }\n}\n```\n\n### Retry with Exponential Backoff — Spring Retry\n\n```java\n\u002F\u002F Add spring-retry + spring-aspects to pom.xml, enable on the app class\n@SpringBootApplication\n@EnableRetry\npublic class Application { \u002F* ... *\u002F }\n\n\u002F\u002F Annotate the operation to retry\n@Service\npublic class EmbeddingService {\n\n    @Retryable(\n        retryFor = { HttpServerErrorException.class, ResourceAccessException.class },\n        maxAttempts = 3,\n        backoff = @Backoff(delay = 1000, multiplier = 2)   \u002F\u002F 1s, 2s, 4s\n    )\n    public float[] embed(String text) {\n        return callExternalEmbeddingApi(text);\n    }\n\n    @Recover\n    public float[] embedFallback(Exception ex, String text) {\n        log.error(\"Embedding failed after retries for text: {}\", text, ex);\n        throw new ServiceUnavailableException(\"Embedding service unavailable\");\n    }\n}\n\n\u002F\u002F Programmatic retry (when annotation isn't flexible enough)\n@Bean\npublic RetryTemplate retryTemplate() {\n    return RetryTemplate.builder()\n        .maxAttempts(3)\n        .exponentialBackoff(1000, 2, 8000)\n        .retryOn(HttpServerErrorException.class)\n        .build();\n}\n\n\u002F\u002F Usage\nretryTemplate.execute(ctx -> embeddingClient.embed(text));\n```\n\n---\n\n## Authentication & Authorization\n\n### JWT with Spring Security\n\n```java\n\u002F\u002F JWT service\n@Service\npublic class JwtService {\n\n    @Value(\"${app.jwt.secret}\")\n    private String secret;\n\n    @Value(\"${app.jwt.expiration-ms:3600000}\")\n    private long expirationMs;\n\n    public String generate(UserPrincipal principal) {\n        return Jwts.builder()\n            .subject(principal.id().toString())\n            .claim(\"email\", principal.email())\n            .claim(\"role\", principal.role().name())\n            .issuedAt(new Date())\n            .expiration(new Date(System.currentTimeMillis() + expirationMs))\n            .signWith(getKey())\n            .compact();\n    }\n\n    public UserPrincipal verify(String token) {\n        Claims claims = Jwts.parser()\n            .verifyWith(getKey())\n            .build()\n            .parseSignedClaims(token)\n            .getPayload();\n\n        return new UserPrincipal(\n            UUID.fromString(claims.getSubject()),\n            claims.get(\"email\", String.class),\n            Role.valueOf(claims.get(\"role\", String.class))\n        );\n    }\n\n    private SecretKey getKey() {\n        return Keys.hmacShaKeyFor(Decoders.BASE64.decode(secret));\n    }\n}\n\n\u002F\u002F JWT filter\n@Component\n@RequiredArgsConstructor\npublic class JwtAuthFilter extends OncePerRequestFilter {\n\n    private final JwtService jwtService;\n    private final UserDetailsService userDetailsService;\n\n    @Override\n    protected void doFilterInternal(HttpServletRequest req,\n            HttpServletResponse res, FilterChain chain)\n            throws ServletException, IOException {\n\n        String authHeader = req.getHeader(\"Authorization\");\n        if (authHeader == null || !authHeader.startsWith(\"Bearer \")) {\n            chain.doFilter(req, res);\n            return;\n        }\n\n        try {\n            String token = authHeader.substring(7);\n            UserPrincipal principal = jwtService.verify(token);\n\n            UsernamePasswordAuthenticationToken auth =\n                new UsernamePasswordAuthenticationToken(\n                    principal, null,\n                    List.of(new SimpleGrantedAuthority(\"ROLE_\" + principal.role().name())));\n\n            SecurityContextHolder.getContext().setAuthentication(auth);\n        } catch (JwtException e) {\n            res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);\n            res.getWriter().write(\"{\\\"error\\\":{\\\"code\\\":\\\"invalid_token\\\",\\\"message\\\":\\\"Invalid or expired token\\\"}}\");\n            return;\n        }\n\n        chain.doFilter(req, res);\n    }\n}\n```\n\n### Role-Based Access Control\n\n```java\n\u002F\u002F Enum-based roles\npublic enum Role { ADMIN, MODERATOR, USER }\n\n\u002F\u002F Method security — enable once in a @Configuration\n@Configuration\n@EnableMethodSecurity\npublic class SecurityConfig { \u002F* ... *\u002F }\n\n\u002F\u002F Controller annotations\n@RestController\n@RequestMapping(\"\u002Fapi\u002Fv1\u002Fmarkets\")\npublic class MarketController {\n\n    @GetMapping          \u002F\u002F any authenticated user\n    public Page\u003CMarketDto> list(Pageable pageable) { \u002F* ... *\u002F }\n\n    @PostMapping         \u002F\u002F any authenticated user\n    public ResponseEntity\u003CMarketDto> create(@Valid @RequestBody CreateMarketRequest req) { \u002F* ... *\u002F }\n\n    @DeleteMapping(\"\u002F{id}\")\n    @PreAuthorize(\"hasRole('ADMIN')\")   \u002F\u002F admin only\n    public ResponseEntity\u003CVoid> delete(@PathVariable UUID id) { \u002F* ... *\u002F }\n\n    @PatchMapping(\"\u002F{id}\u002Fresolve\")\n    @PreAuthorize(\"hasAnyRole('ADMIN', 'MODERATOR')\")\n    public ResponseEntity\u003CMarketDto> resolve(@PathVariable UUID id) { \u002F* ... *\u002F }\n}\n\n\u002F\u002F Ownership check in service layer (finer-grained than annotations)\n@Service\npublic class MarketService {\n\n    @Transactional\n    public void delete(UUID marketId, UserPrincipal principal) {\n        Market market = marketRepository.findById(marketId)\n            .orElseThrow(() -> new ResourceNotFoundException(\"Market not found: \" + marketId));\n\n        boolean isOwner = market.getCreatorId().equals(principal.id());\n        boolean isAdmin = principal.role() == Role.ADMIN;\n\n        if (!isOwner && !isAdmin) {\n            throw new ForbiddenException(\"You do not have permission to delete this market\");\n        }\n\n        marketRepository.delete(market);\n    }\n}\n```\n\n---\n\n## Rate Limiting\n\nRate limiting must use a shared store such as Redis, a gateway, or the platform's native limiter. Do not use per-process in-memory counters for production: they reset on deploy, split across replicas, and fail open in multi-instance or serverless environments.\n\n```java\n\u002F\u002F Bucket4j with Redis (see api-design doc for full implementation)\n@Component\n@RequiredArgsConstructor\npublic class RateLimitFilter extends OncePerRequestFilter {\n\n    private final BucketRepository bucketRepository;  \u002F\u002F Redis-backed\n\n    private static final Map\u003CString, BandwidthDefinition> TIERS = Map.of(\n        \"anonymous\",     Bandwidth.classic(30,  Refill.intervally(30,  Duration.ofMinutes(1))),\n        \"authenticated\", Bandwidth.classic(100, Refill.intervally(100, Duration.ofMinutes(1))),\n        \"premium\",       Bandwidth.classic(1000,Refill.intervally(1000,Duration.ofMinutes(1)))\n    );\n\n    @Override\n    protected void doFilterInternal(HttpServletRequest req,\n            HttpServletResponse res, FilterChain chain)\n            throws ServletException, IOException {\n\n        String tier = resolveTier(req);\n        String key  = resolveKey(req, tier);\n        Bucket bucket = bucketRepository.getOrCreate(key, TIERS.get(tier));\n\n        ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(1);\n        res.addHeader(\"X-RateLimit-Remaining\", String.valueOf(probe.getRemainingTokens()));\n\n        if (!probe.isConsumed()) {\n            res.setStatus(429);\n            res.addHeader(\"Retry-After\", \"60\");\n            return;\n        }\n        chain.doFilter(req, res);\n    }\n\n    private String resolveTier(HttpServletRequest req) {\n        if (req.getHeader(\"X-API-Key\") != null) return \"premium\";\n        if (SecurityContextHolder.getContext().getAuthentication() != null) return \"authenticated\";\n        return \"anonymous\";\n    }\n}\n```\n\n---\n\n## Background Jobs & Async Processing\n\n### Spring @Async (fire-and-forget)\n\n```java\n@SpringBootApplication\n@EnableAsync\npublic class Application { \u002F* ... *\u002F }\n\n\u002F\u002F Thread pool configuration\n@Configuration\npublic class AsyncConfig {\n\n    @Bean(\"taskExecutor\")\n    public Executor taskExecutor() {\n        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();\n        executor.setCorePoolSize(4);\n        executor.setMaxPoolSize(10);\n        executor.setQueueCapacity(100);\n        executor.setThreadNamePrefix(\"async-\");\n        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());\n        executor.initialize();\n        return executor;\n    }\n}\n\n\u002F\u002F Async service method\n@Service\n@Slf4j\npublic class IndexingService {\n\n    @Async(\"taskExecutor\")\n    public CompletableFuture\u003CVoid> indexMarket(UUID marketId) {\n        try {\n            Market market = marketRepository.findById(marketId)\n                .orElseThrow(() -> new ResourceNotFoundException(\"Market not found\"));\n            vectorStore.upsert(market.getId(), embeddingService.embed(market.toText()));\n            log.info(\"Indexed market {}\", marketId);\n        } catch (Exception e) {\n            log.error(\"Failed to index market {}\", marketId, e);\n        }\n        return CompletableFuture.completedFuture(null);\n    }\n}\n\n\u002F\u002F Controller: respond immediately, index in background\n@PostMapping\npublic ResponseEntity\u003CMarketDto> create(@Valid @RequestBody CreateMarketRequest req) {\n    MarketDto created = marketService.create(req);\n    indexingService.indexMarket(created.id());   \u002F\u002F non-blocking\n    return ResponseEntity.status(HttpStatus.CREATED).body(created);\n}\n```\n\n### Scheduled Jobs — Spring @Scheduled\n\n```java\n@Component\n@Slf4j\n@RequiredArgsConstructor\npublic class MarketSyncJob {\n\n    private final MarketSyncService syncService;\n\n    @Scheduled(cron = \"0 0 * * * *\")         \u002F\u002F top of every hour\n    public void syncActiveMarkets() {\n        log.info(\"Starting market sync\");\n        try {\n            int synced = syncService.syncAll();\n            log.info(\"Synced {} markets\", synced);\n        } catch (Exception e) {\n            log.error(\"Market sync failed\", e);\n        }\n    }\n\n    @Scheduled(fixedDelay = 30_000, initialDelay = 10_000)  \u002F\u002F every 30s\n    public void processQueue() {\n        syncService.drainQueue();\n    }\n}\n\n\u002F\u002F Enable scheduling\n@SpringBootApplication\n@EnableScheduling\npublic class Application { \u002F* ... *\u002F }\n```\n\n### Durable Queues with Spring Events + Outbox Pattern\n\nFor operations that must survive restarts, use a transactional outbox instead of `@Async`:\n\n```java\n\u002F\u002F 1. Save the job atomically with the triggering transaction\n@Transactional\npublic MarketDto create(CreateMarketRequest request) {\n    Market market = marketRepository.save(new Market(request));\n    outboxRepository.save(new OutboxEvent(\"market.created\", market.getId().toString()));\n    return MarketDto.from(market);\n}\n\n\u002F\u002F 2. Poll the outbox table and dispatch\n@Scheduled(fixedDelay = 5_000)\n@Transactional\npublic void processOutbox() {\n    List\u003COutboxEvent> pending = outboxRepository.findPendingWithLock(10);\n    pending.forEach(event -> {\n        try {\n            dispatch(event);\n            event.markProcessed();\n        } catch (Exception e) {\n            event.incrementRetries();\n            log.error(\"Failed to dispatch event {}\", event.getId(), e);\n        }\n    });\n}\n```\n\n---\n\n## Logging & Monitoring\n\n### Structured Logging with SLF4J + Logback + MDC\n\n```java\n\u002F\u002F logback-spring.xml — JSON output for log aggregators (Datadog, Loki, CloudWatch)\n\u002F\u002F Use logstash-logback-encoder:\n\u002F\u002F \u003Cdependency>\n\u002F\u002F   \u003CgroupId>net.logstash.logback\u003C\u002FgroupId>\n\u002F\u002F   \u003CartifactId>logstash-logback-encoder\u003C\u002FartifactId>\n\u002F\u002F \u003C\u002Fdependency>\n```\n\n```xml\n\u003C!-- logback-spring.xml -->\n\u003Cappender name=\"JSON\" class=\"ch.qos.logback.core.ConsoleAppender\">\n  \u003Cencoder class=\"net.logstash.logback.encoder.LogstashEncoder\">\n    \u003CincludeMdcKeyName>requestId\u003C\u002FincludeMdcKeyName>\n    \u003CincludeMdcKeyName>userId\u003C\u002FincludeMdcKeyName>\n    \u003CincludeMdcKeyName>traceId\u003C\u002FincludeMdcKeyName>\n  \u003C\u002Fencoder>\n\u003C\u002Fappender>\n\n\u003Croot level=\"INFO\">\n  \u003Cappender-ref ref=\"JSON\"\u002F>\n\u003C\u002Froot>\n```\n\n```java\n\u002F\u002F Request filter — populate MDC for every request\n@Component\n@Order(Ordered.HIGHEST_PRECEDENCE)\npublic class MdcFilter extends OncePerRequestFilter {\n\n    @Override\n    protected void doFilterInternal(HttpServletRequest req,\n            HttpServletResponse res, FilterChain chain)\n            throws ServletException, IOException {\n\n        String requestId = Optional.ofNullable(req.getHeader(\"X-Request-Id\"))\n            .orElse(UUID.randomUUID().toString());\n\n        MDC.put(\"requestId\", requestId);\n        MDC.put(\"method\", req.getMethod());\n        MDC.put(\"path\", req.getRequestURI());\n\n        \u002F\u002F If JWT is already parsed, attach userId\n        Authentication auth = SecurityContextHolder.getContext().getAuthentication();\n        if (auth != null && auth.getPrincipal() instanceof UserPrincipal p) {\n            MDC.put(\"userId\", p.id().toString());\n        }\n\n        try {\n            chain.doFilter(req, res);\n        } finally {\n            MDC.clear();   \u002F\u002F critical — thread pool reuse means stale MDC leaks\n        }\n    }\n}\n\n\u002F\u002F Service-level logging — MDC fields are added automatically\n@Service\n@Slf4j\npublic class MarketService {\n\n    public MarketDto findById(UUID id) {\n        log.info(\"Fetching market\");   \u002F\u002F requestId, userId added by MDC filter\n        return marketRepository.findById(id)\n            .map(MarketDto::from)\n            .orElseThrow(() -> {\n                log.warn(\"Market not found: {}\", id);\n                return new ResourceNotFoundException(\"Market not found: \" + id);\n            });\n    }\n}\n```\n\n### Actuator & Health Checks\n\n```yaml\n# application.yml\nmanagement:\n  endpoints:\n    web:\n      exposure:\n        include: health, info, metrics, prometheus\n      base-path: \u002Finternal\n  endpoint:\n    health:\n      show-details: when-authorized\n  metrics:\n    tags:\n      application: ${spring.application.name}\n```\n\n```java\n\u002F\u002F Custom health indicator\n@Component\n@RequiredArgsConstructor\npublic class VectorStoreHealthIndicator implements HealthIndicator {\n\n    private final VectorStore vectorStore;\n\n    @Override\n    public Health health() {\n        try {\n            vectorStore.ping();\n            return Health.up().withDetail(\"vectorStore\", \"reachable\").build();\n        } catch (Exception e) {\n            return Health.down().withDetail(\"vectorStore\", e.getMessage()).build();\n        }\n    }\n}\n```\n\n---\n\n## React: Consuming Backend Patterns\n\n### Retry and Error Boundary\n\n```tsx\n\u002F\u002F src\u002Fcomponents\u002FAsyncBoundary.tsx — wraps TanStack Query errors\nimport { QueryErrorResetBoundary } from \"@tanstack\u002Freact-query\";\nimport { ErrorBoundary } from \"react-error-boundary\";\n\nexport function AsyncBoundary({ children }: { children: React.ReactNode }) {\n  return (\n    \u003CQueryErrorResetBoundary>\n      {({ reset }) => (\n        \u003CErrorBoundary\n          onReset={reset}\n          fallbackRender={({ error, resetErrorBoundary }) => (\n            \u003Cdiv role=\"alert\">\n              \u003Cp>Something went wrong: {error.message}\u003C\u002Fp>\n              \u003Cbutton onClick={resetErrorBoundary}>Retry\u003C\u002Fbutton>\n            \u003C\u002Fdiv>\n          )}\n        >\n          {children}\n        \u003C\u002FErrorBoundary>\n      )}\n    \u003C\u002FQueryErrorResetBoundary>\n  );\n}\n```\n\n### Optimistic Updates\n\n```tsx\n\u002F\u002F src\u002Fhooks\u002FuseMarkets.ts\nexport function useDeleteMarket() {\n  const queryClient = useQueryClient();\n\n  return useMutation({\n    mutationFn: marketsApi.delete,\n\n    onMutate: async (id: string) => {\n      await queryClient.cancelQueries({ queryKey: marketKeys.list() });\n      const previous = queryClient.getQueryData(marketKeys.list());\n\n      \u002F\u002F Optimistically remove from list\n      queryClient.setQueryData(marketKeys.list(), (old: PagedResponse\u003CMarketDto>) => ({\n        ...old,\n        data: old.data.filter((m) => m.id !== id),\n      }));\n\n      return { previous };\n    },\n\n    onError: (_err, _id, context) => {\n      \u002F\u002F Rollback on failure\n      queryClient.setQueryData(marketKeys.list(), context?.previous);\n    },\n\n    onSettled: () => {\n      queryClient.invalidateQueries({ queryKey: marketKeys.list() });\n    },\n  });\n}\n```\n\n### Background Refetching and Polling\n\n```tsx\n\u002F\u002F Poll for a resource until its status changes (e.g., async job completion)\nexport function useMarket(id: string) {\n  return useQuery({\n    queryKey: marketKeys.detail(id),\n    queryFn: () => marketsApi.getById(id),\n    refetchInterval: (query) => {\n      const status = query.state.data?.status;\n      \u002F\u002F Stop polling once the job finishes\n      return status === \"indexing\" ? 3000 : false;\n    },\n  });\n}\n```\n\n---\n\n## Architecture Layering Reference\n\n```\nController        — HTTP binding (@RestController, @Valid, ResponseEntity)\n     ↓\nService           — Business logic, @Transactional, @Cacheable\n     ↓\nRepository        — Data access (JpaRepository, @Query, Specification)\n     ↓\nDatabase          — PostgreSQL \u002F Redis \u002F Vector store\n```\n\n**Rules:**\n- Controllers never call repositories directly — only services.\n- Services own transactions; repositories are transaction-aware but don't define them.\n- DTOs cross the controller ↔ service boundary; domain entities stay in service ↔ repository.\n- Never expose JPA entities in API responses — mapper to DTO first.\n\n---\n\n## Checklist\n\nBefore shipping a new feature:\n\n- [ ] Controller delegates to service — no business logic in `@RestController`\n- [ ] `@Transactional(readOnly = true)` on service class, `@Transactional` on mutating methods only\n- [ ] N+1 queries eliminated — verified with SQL logging enabled\n- [ ] Projections used for list endpoints instead of full entities\n- [ ] `@Valid` on all `@RequestBody` parameters\n- [ ] `@RestControllerAdvice` handles all exception types\n- [ ] `@Cacheable` \u002F `@CacheEvict` applied at service layer, not controller\n- [ ] Async jobs (`@Async`) don't swallow exceptions — use `CompletableFuture` or a recovery method\n- [ ] MDC populated per-request and cleared in `finally`\n- [ ] No JPA entities serialized to JSON — always map to DTOs\n- [ ] React query keys follow `[resource, action, params]` structure\n- [ ] Optimistic updates with rollback for destructive mutations\n- [ ] `AsyncBoundary` wraps all data-fetching subtrees",{"name":5,"metadata":24,"description":7},{"origin":25},"AgentPowerHouse - APH","main","2ee82a0e0feb330a9ca82ac22e29268605a07a97","plugins\u002Fcore\u002Fskills\u002Fbackend-patterns",0,"https:\u002F\u002Fgithub.com\u002Fzeeroiq\u002Fagent-powerhouse","https:\u002F\u002Fgithub.com\u002Fzeeroiq","2026-09-14 03:10:44",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add zeeroiq\u002Fagent-powerhouse --skill backend-patterns",{"tool":39,"command":40},"bunx","bunx skills add zeeroiq\u002Fagent-powerhouse --skill backend-patterns",{"tool":42,"command":43},"pnpm","pnpm dlx skills add zeeroiq\u002Fagent-powerhouse --skill backend-patterns","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fzeeroiq\u002Fagent-powerhouse\u002Fblob\u002Fmain\u002Fplugins\u002Fcore\u002Fskills\u002Fbackend-patterns\u002FSKILL.md",true,[],[48,55,62,69,76,83],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":19},"01M75TK43N4Y1HHF88DJ95XDSC","springboot-verification","Verification loop for Spring Boot projects: build, static analysis, tests with coverage, security scans, and diff review before release or PR.","https:\u002F\u002Fgithub.com\u002Fzeeroiq\u002Fagent-powerhouse\u002Fblob\u002Fmain\u002Fplugins\u002Fjava\u002Fskills\u002Fspringboot-verification\u002FSKILL.md",[],[],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M75TK18END7AKP4FQMSFEB4B","springboot-tdd","Test-driven development for Spring Boot using JUnit 5, Mockito, MockMvc, Testcontainers, and JaCoCo. Use when adding features, fixing bugs, or refactoring.","https:\u002F\u002Fgithub.com\u002Fzeeroiq\u002Fagent-powerhouse\u002Fblob\u002Fmain\u002Fplugins\u002Fjava\u002Fskills\u002Fspringboot-tdd\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M75TJYRM9Z2JQ41QD7G8YSN7","springboot-security","Spring Security best practices for authn\u002Fauthz, validation, CSRF, secrets, headers, rate limiting, and dependency security in Java Spring Boot services.","https:\u002F\u002Fgithub.com\u002Fzeeroiq\u002Fagent-powerhouse\u002Fblob\u002Fmain\u002Fplugins\u002Fjava\u002Fskills\u002Fspringboot-security\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M75TJV6FW8P7S0RE2PYB5S49","springboot-patterns","Spring Boot architecture patterns, REST API design, layered services, data access, caching, async processing, and logging. Use for Java Spring Boot backend work.","https:\u002F\u002Fgithub.com\u002Fzeeroiq\u002Fagent-powerhouse\u002Fblob\u002Fmain\u002Fplugins\u002Fjava\u002Fskills\u002Fspringboot-patterns\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M75TJQVREKZ4DWT5DMX1Z3R5","quarkus-tdd","Test-driven development for Quarkus 3.x LTS using JUnit 5, Mockito, REST Assured, Camel testing, and JaCoCo. Use when adding features, fixing bugs, or refactoring event-driven services.","https:\u002F\u002Fgithub.com\u002Fzeeroiq\u002Fagent-powerhouse\u002Fblob\u002Fmain\u002Fplugins\u002Fjava\u002Fskills\u002Fquarkus-tdd\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M75TJM4P1G4WZ523TKHSQ4GZ","quarkus-security","Quarkus Security best practices for authentication, authorization, JWT\u002FOIDC, RBAC, input validation, CSRF, secrets management, and dependency security.","https:\u002F\u002Fgithub.com\u002Fzeeroiq\u002Fagent-powerhouse\u002Fblob\u002Fmain\u002Fplugins\u002Fjava\u002Fskills\u002Fquarkus-security\u002FSKILL.md",[],[]]