javi-forge 0.1.0

package/ai-config/skills/backend/bff-concepts/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: bff-concepts
+description: >
+  Backend for Frontend pattern. Client-specific APIs, response tailoring, aggregation.
+  Trigger: BFF, backend for frontend, aggregation, client-specific, mobile API
+tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+metadata:
+  author: apigen-team
+  version: "1.0"
+  tags: [bff, architecture, api-design, microservices]
+  scope: ["**/bff/**"]
+---
+
+# Backend for Frontend (BFF) Pattern
+
+## Core Concept
+
+```
+Traditional API:
+┌─────────────────────────────────────────┐
+│         Single Generic API              │
+│  (serves Web, Mobile, TV, Partners)     │
+└─────────────────────────────────────────┘
+         ↓         ↓         ↓
+      [Web]    [Mobile]    [TV]
+   (over-fetching + under-fetching)
+
+BFF Pattern:
+┌───────────┐ ┌───────────┐ ┌───────────┐
+│  Web BFF  │ │Mobile BFF │ │  TV BFF   │
+└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
+      ↓             ↓             ↓
+┌─────────────────────────────────────────┐
+│         Backend Microservices           │
+└─────────────────────────────────────────┘
+```
+
+## Client Types
+
+### Web BFF
+```
+Characteristics:
+- Full data payloads (fast connections)
+- Rich interaction capabilities
+- SEO requirements (SSR data)
+- Complex filtering/sorting UI
+
+Typical operations:
+- Large paginated lists
+- Real-time updates (WebSocket)
+- Complex search queries
+- File uploads
+```
+
+### Mobile BFF
+```
+Characteristics:
+- Bandwidth optimization
+- Battery conservation
+- Offline support (sync)
+- Push notifications
+
+Optimizations:
+- Compressed responses
+- Delta sync (only changes)
+- Image CDN URLs (different sizes)
+- Aggressive caching headers
+```
+
+### IoT / Embedded BFF
+```
+Characteristics:
+- Minimal payloads
+- Low memory footprint
+- Binary protocols (gRPC/MQTT)
+- Intermittent connectivity
+
+Patterns:
+- Batch operations
+- Store-and-forward
+- Heartbeat polling
+```
+
+## Response Tailoring
+
+### Field Selection
+```json
+// Web: Full response
+{
+  "user": {
+    "id": "123",
+    "name": "John Doe",
+    "email": "john@example.com",
+    "avatar": "https://...",
+    "bio": "...",
+    "preferences": {...},
+    "stats": {...}
+  }
+}
+
+// Mobile: Tailored response
+{
+  "user": {
+    "id": "123",
+    "name": "John Doe",
+    "avatar_thumb": "https://.../48x48"
+  }
+}
+```
+
+### Aggregation Strategies
+```
+Sequential:
+1. Get user profile
+2. Get user's orders
+3. Get recommendations
+4. Combine and return
+
+Parallel:
+1. Fork: [profile, orders, recommendations]
+2. Join: Combine results
+3. Return aggregated response
+
+Conditional:
+1. Get user profile
+2. IF premium user THEN get recommendations
+3. Return appropriate response
+```
+
+## Rate Limiting per Client
+
+```
+Web clients:
+- 1000 req/min (authenticated)
+- 100 req/min (anonymous)
+
+Mobile clients:
+- 500 req/min (aggressive caching expected)
+
+Partner APIs:
+- Per-contract limits
+- Separate quotas per partner
+```
+
+## Query Composition
+
+### GraphQL-like Behavior
+```
+Request:
+GET /bff/dashboard?include=profile,notifications,orders
+
+Response:
+{
+  "profile": {...},
+  "notifications": [...],
+  "orders": [...]
+}
+
+Backend calls:
+- GET /users/me → profile
+- GET /notifications?limit=5 → notifications
+- GET /orders?status=pending → orders
+```
+
+### Partial Failure Handling
+```json
+{
+  "profile": {...},
+  "notifications": {
+    "_error": "Service temporarily unavailable",
+    "_fallback": []
+  },
+  "orders": [...]
+}
+```
+
+## Caching Strategies
+
+```
+Per-client-type:
+- Web: 5 min cache, ETags
+- Mobile: 30 min cache, stale-while-revalidate
+- IoT: 1 hour cache
+
+Per-resource:
+- User profile: 5 min
+- Product catalog: 1 hour
+- Recommendations: 15 min
+```
+
+## Implementation Patterns
+
+### Request/Response DTOs
+```
+// Client-specific DTOs
+WebUserResponse:
+  - All fields
+  - Nested objects
+  - Full links
+
+MobileUserResponse:
+  - Essential fields only
+  - IDs instead of nested objects
+  - Thumbnail URLs
+```
+
+### Service Orchestration
+```
+BFF Controller:
+1. Parse client context (User-Agent, Accept)
+2. Determine required data
+3. Call services (parallel when possible)
+4. Apply transformations
+5. Return tailored response
+```
+
+## Anti-patterns to Avoid
+
+```
+❌ Business logic in BFF
+   → BFF should only orchestrate and transform
+
+❌ Direct database access
+   → Always go through services
+
+❌ Shared BFF for different clients
+   → Each client type needs its own BFF
+
+❌ Duplicating validation
+   → Let backend services handle validation
+```
+
+## Related Skills
+
+- `bff-spring`: Spring Boot BFF implementation

package/ai-config/skills/backend/bff-spring/SKILL.md

@@ -0,0 +1,364 @@
+---
+name: bff-spring
+description: >
+  Spring Boot BFF implementation. Client detection, response tailoring, service composition.
+  Trigger: apigen-bff, BaseBffController, ClientType, TailorForClient, aggregation
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+metadata:
+  author: apigen-team
+  version: "1.0"
+  tags: [bff, spring-boot, aggregation, java]
+  scope: ["apigen-bff/**"]
+---
+
+# BFF Spring Boot (apigen-bff)
+
+## Configuration
+
+```yaml
+apigen:
+  bff:
+    enabled: true
+
+    client-detection:
+      header: X-Client-Type
+      fallback: WEB
+
+    rate-limits:
+      web:
+        requests-per-minute: 1000
+      mobile:
+        requests-per-minute: 500
+      iot:
+        requests-per-minute: 100
+
+    response-tailoring:
+      enabled: true
+      compress-mobile: true
+
+    composition:
+      timeout: 5s
+      parallel-enabled: true
+```
+
+## Client Type Detection
+
+```java
+public enum ClientType {
+    WEB("web"),
+    MOBILE_IOS("ios"),
+    MOBILE_ANDROID("android"),
+    TABLET("tablet"),
+    TV("tv"),
+    IOT("iot"),
+    PARTNER("partner");
+
+    public boolean isMobile() {
+        return this == MOBILE_IOS || this == MOBILE_ANDROID;
+    }
+
+    public boolean requiresCompression() {
+        return isMobile() || this == IOT;
+    }
+}
+```
+
+## Annotations
+
+```java
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface BffEndpoint {
+    ClientType[] clients() default {};
+    String[] include() default {};
+    boolean aggregate() default false;
+}
+
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface TailorForClient {
+    ClientType value();
+    String[] fields() default {};
+    boolean compress() default false;
+}
+```
+
+## Base BFF Controller
+
+```java
+@RestController
+@RequestMapping("/bff")
+public abstract class BaseBffController {
+
+    protected final QueryCompositionService compositionService;
+    protected final ResponseTailoringService tailoringService;
+    protected final CombinedRateLimitService rateLimitService;
+
+    protected ClientType detectClient(HttpServletRequest request) {
+        String clientHeader = request.getHeader("X-Client-Type");
+        if (clientHeader != null) {
+            return ClientType.fromValue(clientHeader);
+        }
+
+        String userAgent = request.getHeader("User-Agent");
+        return ClientTypeDetector.fromUserAgent(userAgent);
+    }
+
+    protected <T> T tailorResponse(T response, ClientType clientType) {
+        return tailoringService.tailor(response, clientType);
+    }
+}
+```
+
+## Query Composition Service
+
+```java
+@Service
+public class QueryCompositionServiceImpl implements QueryCompositionService {
+
+    private final List<ServiceRequest> serviceRequests;
+    private final ExecutorService executor;
+
+    @Override
+    public AggregatedResponse compose(List<String> includes,
+                                       Map<String, Object> params) {
+
+        List<CompletableFuture<ServiceResult>> futures = includes.stream()
+            .map(include -> findServiceRequest(include))
+            .map(sr -> CompletableFuture.supplyAsync(
+                () -> executeService(sr, params), executor)
+                .exceptionally(this::handleFailure))
+            .toList();
+
+        CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
+            .orTimeout(5, TimeUnit.SECONDS)
+            .join();
+
+        return aggregateResults(futures);
+    }
+
+    private ServiceResult handleFailure(Throwable ex) {
+        log.warn("Service call failed: {}", ex.getMessage());
+        return ServiceResult.failure(ex.getMessage());
+    }
+}
+```
+
+## Response Tailoring Service
+
+```java
+@Service
+public class ResponseTailoringServiceImpl implements ResponseTailoringService {
+
+    private final ObjectMapper objectMapper;
+    private final Map<ClientType, Set<String>> fieldMappings;
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public <T> T tailor(T response, ClientType clientType) {
+        if (response == null) return null;
+
+        Set<String> allowedFields = fieldMappings.get(clientType);
+        if (allowedFields == null || allowedFields.isEmpty()) {
+            return response;
+        }
+
+        // Convert to map, filter fields, convert back
+        Map<String, Object> map = objectMapper.convertValue(response, Map.class);
+        Map<String, Object> filtered = filterFields(map, allowedFields);
+
+        return (T) objectMapper.convertValue(filtered, response.getClass());
+    }
+
+    private Map<String, Object> filterFields(Map<String, Object> source,
+                                              Set<String> allowed) {
+        return source.entrySet().stream()
+            .filter(e -> allowed.contains(e.getKey()))
+            .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));
+    }
+}
+```
+
+## Aggregated Response Model
+
+```java
+public record AggregatedResponse(
+    Map<String, Object> data,
+    Map<String, ErrorInfo> errors,
+    ResponseMetadata metadata
+) {
+    public boolean hasErrors() {
+        return errors != null && !errors.isEmpty();
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static class Builder {
+        private final Map<String, Object> data = new HashMap<>();
+        private final Map<String, ErrorInfo> errors = new HashMap<>();
+
+        public Builder addData(String key, Object value) {
+            data.put(key, value);
+            return this;
+        }
+
+        public Builder addError(String key, String message) {
+            errors.put(key, new ErrorInfo(message, null));
+            return this;
+        }
+
+        public AggregatedResponse build() {
+            return new AggregatedResponse(data, errors,
+                new ResponseMetadata(Instant.now()));
+        }
+    }
+}
+```
+
+## BFF Endpoint Aspect
+
+```java
+@Aspect
+@Component
+public class BffEndpointAspect {
+
+    private final CombinedRateLimitService rateLimitService;
+
+    @Around("@annotation(bffEndpoint)")
+    public Object handleBffEndpoint(ProceedingJoinPoint joinPoint,
+                                     BffEndpoint bffEndpoint) throws Throwable {
+
+        HttpServletRequest request = getCurrentRequest();
+        ClientType clientType = detectClient(request);
+
+        // Check client type restriction
+        if (bffEndpoint.clients().length > 0 &&
+            !Arrays.asList(bffEndpoint.clients()).contains(clientType)) {
+            throw new ClientTypeNotAllowedException(clientType);
+        }
+
+        // Apply rate limiting
+        rateLimitService.checkLimit(clientType, request);
+
+        return joinPoint.proceed();
+    }
+}
+```
+
+## Example BFF Controller
+
+```java
+@RestController
+@RequestMapping("/bff/v1")
+public class DashboardBffController extends BaseBffController {
+
+    private final UserService userService;
+    private final OrderService orderService;
+    private final NotificationService notificationService;
+
+    @GetMapping("/dashboard")
+    @BffEndpoint(aggregate = true)
+    public AggregatedResponse getDashboard(
+            @RequestParam(defaultValue = "profile,notifications") String include,
+            HttpServletRequest request) {
+
+        ClientType client = detectClient(request);
+        List<String> includes = Arrays.asList(include.split(","));
+
+        AggregatedResponse.Builder builder = AggregatedResponse.builder();
+
+        if (includes.contains("profile")) {
+            UserDTO profile = userService.getCurrentUser();
+            builder.addData("profile", tailorResponse(profile, client));
+        }
+
+        if (includes.contains("notifications")) {
+            int limit = client.isMobile() ? 5 : 20;
+            List<NotificationDTO> notifications =
+                notificationService.getRecent(limit);
+            builder.addData("notifications", notifications);
+        }
+
+        if (includes.contains("orders")) {
+            List<OrderDTO> orders = orderService.getRecentOrders();
+            builder.addData("orders", tailorResponse(orders, client));
+        }
+
+        return builder.build();
+    }
+
+    @GetMapping("/dashboard")
+    @TailorForClient(value = ClientType.MOBILE_IOS,
+                     fields = {"id", "name", "avatarThumb"})
+    public MobileDashboardResponse getMobileDashboard() {
+        // iOS-specific optimized response
+    }
+}
+```
+
+## Rate Limiting Service
+
+```java
+@Service
+public class CombinedRateLimitServiceImpl implements CombinedRateLimitService {
+
+    private final Map<ClientType, Bucket> buckets = new ConcurrentHashMap<>();
+    private final BffProperties properties;
+
+    @Override
+    public void checkLimit(ClientType clientType, HttpServletRequest request) {
+        Bucket bucket = buckets.computeIfAbsent(clientType, this::createBucket);
+
+        if (!bucket.tryConsume(1)) {
+            throw new RateLimitExceededException(
+                "Rate limit exceeded for client type: " + clientType);
+        }
+    }
+
+    private Bucket createBucket(ClientType clientType) {
+        int rpm = properties.getRateLimits()
+            .getOrDefault(clientType, 100);
+
+        return Bucket.builder()
+            .addLimit(Bandwidth.simple(rpm, Duration.ofMinutes(1)))
+            .build();
+    }
+}
+```
+
+## Testing
+
+```java
+@WebMvcTest(DashboardBffController.class)
+class DashboardBffControllerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockBean
+    private UserService userService;
+
+    @Test
+    void shouldTailorResponseForMobile() throws Exception {
+        when(userService.getCurrentUser()).thenReturn(fullUserDto());
+
+        mockMvc.perform(get("/bff/v1/dashboard")
+                .header("X-Client-Type", "ios"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.data.profile.email").doesNotExist())
+            .andExpect(jsonPath("$.data.profile.id").exists());
+    }
+}
+```
+
+## Related Skills
+
+- `bff-concepts`: BFF pattern concepts
+- `spring-boot-4`: Spring Boot 4.0 patterns