Uc Patterns

SKILL: UC Enterprise Patterns (SkullRender Standard)

[!IMPORTANT] Philosophy: Enterprise patterns applied to ALL Use Cases, regardless of type. This skill is modular - apply only the patterns relevant to your UC type.

Scope: Backend architecture (FastAPI + LangGraph + External Services)

When to Use

• Designing new Use Cases for any SkullRender project
• Refactoring existing UCs for production readiness
• Adding observability, security, or resilience to any endpoint
• Code reviews involving critical endpoints
• ANY UC type: CRUD, LLM, Integration, Auth, Background Jobs

UC Type Classification

Before applying patterns, classify your UC:

Critical Patterns (The "Must Haves")

1. Observability (Required for ALL UCs)

Effort: 2-3 days per UC

Structured Logging (JSON, GDPR-compliant):

# Standard log format - adapt fields per UC
{
  "timestamp": "2026-02-08T16:56:36Z",
  "level": "INFO",
  "event": "{uc}_{event_type}",
  "correlation_id": "uuid",
  "user_id": "auth0|abc123",  # Omit for public endpoints
  "ip_hash": "ip_a3f9c2d1e4b5a678",  # Always anonymized
  "duration_ms": 245  # For completed events
}

IP Anonymization (GDPR - always apply):

import hashlib
from datetime import datetime
import os

def anonymize_ip(ip: str, date: str | None = None) -> str:
    if date is None:
        date = datetime.now().date().isoformat()
    daily_salt = os.getenv("IP_SALT_SECRET") + date
    hashed = hashlib.sha256(f"{ip}:{daily_salt}".encode()).hexdigest()[:16]
    return f"ip_{hashed}"

Standard Events (adapt per UC):

Prometheus Metrics (choose relevant):

OpenTelemetry Spans:

{uc}_request (root)
├── guard_validation
├── domain_logic
├── [external_call]  # Only if applicable
└── [persistence]    # Only if writes data

2. Security Hardening (Apply per UC type)

Effort: 1-3 days depending on UC type

2.1 Rate Limiting (ALL UCs)

# Per-user limit (authenticated)
@limiter.limit("60 per minute", key_func=get_user_id)
# Per-IP limit (public/DDoS protection)
@limiter.limit("100 per hour", key_func=lambda: request.client.host)

2.2 Prompt Injection Detection (LLM UCs ONLY)

import re

INJECTION_PATTERNS = [
    r"ignore\s+(all\s+)?previous\s+instructions?",
    r"you\s+are\s+now\s+(a\s+)?",
    r"forget\s+(everything|all|your\s+instructions)",
    r"system\s*:\s*",
    r"<\|im_start\|>",
    r"</s>",
    r"\[INST\]",
    r"sudo\s+mode",
    r"developer\s+mode",
    r"jailbreak"
]

def detect_prompt_injection(message: str) -> tuple[bool, str]:
    for pattern in INJECTION_PATTERNS:
        match = re.search(pattern, message, re.IGNORECASE)
        if match:
            return True, pattern
    return False, ""

2.3 Output Sanitization (User-facing responses)

import bleach

def sanitize_output(response: str) -> str:
    return bleach.clean(response, tags=[], strip=True)

2.4 Brute Force Protection (Auth UCs ONLY)

# Track failed attempts per user/IP
# Lock after 5 failures for 15 minutes
@limiter.limit("5 per 15 minutes", key_func=get_login_key)

2.5 URL/Path Validation (Integration UCs)

ALLOWED_DOMAINS = ["github.com", "docs.google.com", ...]

def validate_url(url: str) -> bool:
    parsed = urlparse(url)
    return parsed.netloc in ALLOWED_DOMAINS

3. Correlation ID (Required for ALL UCs)

Effort: 1 day (one-time setup)

Middleware (apply once, works for all UCs):

import uuid
from contextvars import ContextVar

correlation_id_var: ContextVar[str] = ContextVar("correlation_id")

@app.middleware("http")
async def correlation_id_middleware(request: Request, call_next):
    correlation_id = request.headers.get("X-Correlation-ID", str(uuid.uuid4()))
    correlation_id_var.set(correlation_id)
    response = await call_next(request)
    response.headers["X-Correlation-ID"] = correlation_id
    return response

def get_correlation_id() -> str:
    return correlation_id_var.get("unknown")

Propagation Points:

4. Circuit Breaker (External service calls ONLY)

Effort: 1 day per service type

Apply when: UC calls any external service (LLM, database, API, MCP)

from circuitbreaker import circuit

class ServiceError(Exception):
    pass

@circuit(
    failure_threshold=5,
    recovery_timeout=60,
    expected_exception=ServiceError
)
async def call_external_service(config: ServiceConfig):
    try:
        return await service.call(config)
    except TimeoutError:
        raise ServiceError("Service timeout")
    except ConnectionError:
        raise ServiceError("Service unavailable")

Circuit States:

Configuration by Service Type:

Anti-Patterns (The "Never Do's")

• ❌ Log PII without anonymization (IP, email, user-agent)
• ❌ Call external services without circuit breaker
• ❌ Omit correlation ID in logs or external calls
• ❌ Trust user input without validation
• ❌ Expose stack traces in HTTP responses
• ❌ Hardcode rate limits (use config per tier)
• ❌ Apply LLM-specific patterns to non-LLM UCs
• ❌ Skip observability for "simple" CRUD operations

UC Documentation Template

Use this template when documenting ANY Use Case:

### UC-XX: [Name]

**Type:** [CRUD | LLM | Auth | Integration | Query | Background]
**Actor:** [Who triggers]  
**Goal:** [What they want]  
**Preconditions:** [List]

**Related Use Cases:** [UC-YY if handoff exists]

---

#### Guard Clauses (Fail-Fast)

1. [Auth/Authz] - if authenticated UC
2. [Rate Limiting] - always
3. [Input Validation] - always
4. [Quota Check] - if applicable
5. [Prompt Injection] - LLM UCs only

#### Domain Flow (Business Logic)

[Numbered steps - what changes in the system]

#### Technical Flow (Implementation)

[Sequence diagram - include Logger, Metrics participants]

#### Applied Patterns

| Pattern | Applied? | Notes |
|---------|----------|-------|
| Observability | ✅/❌ | [Events, metrics, spans] |
| Security | ✅/❌ | [Which guards applied] |
| Correlation ID | ✅/❌ | [Propagation points] |
| Circuit Breaker | ✅/❌ | [Which services] |

Pattern Application Matrix

Quick reference for which patterns to apply:

Legend: ✅ Required | ❓ Conditional | ❌ Not Applicable

Production Ready Checklist

Apply per UC type (check only relevant items):

All UCs

• Guard clauses documented (fail-fast order)
• Domain Flow separated from Technical Flow
• Structured logging GDPR-compliant
• Prometheus metrics defined
• Correlation ID propagated
• Error handling with specific HTTP codes
• Rate limiting configured

LLM UCs (additional)

• Prompt injection detection
• Output sanitization
• LLM circuit breaker
• Token usage logged

Integration UCs (additional)

• URL/path validation
• External service circuit breaker
• Timeout handling

Auth UCs (additional)

• Brute force protection
• Token/session expiration
• Audit logging

Related Skills

• app-security — PII sanitization, Secret Detection
• clean-code — Strict typing, validation
• typescript — Interface exports to frontend
• angular — Interceptor for correlation ID

Trigger & Enforcement

• PLANNING: Apply when designing new UCs (choose patterns based on UC type)
• EXECUTION: Implement selected patterns
• VERIFICATION: Validate all applicable patterns are in place