@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/backend-review.md

@@ -0,0 +1,868 @@
+# Backend Code Review - Complete Guide
+
+Comprehensive backend code review covering multi-language patterns, runtime behavior, architecture, and production readiness.
+
+---
+
+## 🎯 Backend Review Philosophy
+
+### Core Perspective: Business Logic → System Architecture → Runtime Behavior
+
+Backend CR evaluates code from multiple layers, **simulating production scenarios** including load, failure, and concurrency.
+
+```
+Review Layers:
+┌─────────────────────────────────────────┐
+│  Layer 1: Business Logic                │
+│  - Requirements implementation          │
+│  - Domain model correctness             │
+│  - Edge case handling                   │
+└─────────────────────────────────────────┘
+         ↓
+┌─────────────────────────────────────────┐
+│  Layer 2: System Architecture           │
+│  - Module coupling/cohesion             │
+│  - Service boundaries                   │
+│  - Data flow design                     │
+└─────────────────────────────────────────┘
+         ↓
+┌─────────────────────────────────────────┐
+│  Layer 3: Runtime Behavior              │
+│  - Performance under load               │
+│  - Failure recovery                     │
+│  - Concurrent operation safety          │
+└─────────────────────────────────────────┘
+```
+
+### Language-Agnostic Principles
+
+| Principle | Description | Application |
+|-----------|-------------|-------------|
+| **SOLID** | Single responsibility, Open-closed, etc. | All OOP languages |
+| **DRY** | Don't Repeat Yourself | All languages |
+| **KISS** | Keep It Simple, Stupid | All languages |
+| **YAGNI** | You Aren't Gonna Need It | All languages |
+
+### Language-Specific Considerations
+
+| Language | Key Focus Areas |
+|----------|-----------------|
+| **Java** | GC tuning, thread pool sizing, memory model |
+| **Node.js** | Single-thread blocking, event loop, Promise handling |
+| **Go** | Goroutine lifecycle, channel deadlock, race conditions |
+| **Python** | GIL limitations, async/sync mixing, memory leaks |
+| **C#** | Async context, IDisposable, LINQ efficiency |
+
+---
+
+## 🛠️ Tool Stack by Language
+
+### Mandatory Pre-Review Scans
+
+#### Java
+
+```bash
+# Static Analysis
+mvn spotbugs:check          # Bug patterns
+mvn pmd:check               # Code style violations
+mvn checkstyle:check        # Style enforcement
+
+# Security
+mvn dependency-check:check  # OWASP dependency scan
+
+# Coverage
+mvn jacoco:report           # Target: >80%
+```
+
+#### Node.js / TypeScript
+
+```bash
+# Static Analysis
+npx eslint . --max-warnings 0
+npx tsc --noEmit
+
+# Security
+npm audit                    # Vulnerability scan
+npx snyk test               # Deep security scan
+
+# Coverage
+npx jest --coverage --coverageThreshold='{"global":{"lines":80}}'
+```
+
+#### Go
+
+```bash
+# Static Analysis
+golangci-lint run           # Comprehensive linter
+go vet ./...                # Common mistakes
+staticcheck ./...           # Advanced checks
+
+# Race Detection
+go test -race ./...
+
+# Coverage
+go test -cover ./...
+```
+
+#### Python
+
+```bash
+# Static Analysis
+pylint src/
+flake8 src/
+mypy src/ --strict
+
+# Security
+bandit -r src/               # Security linter
+safety check                 # Dependency vulnerabilities
+
+# Coverage
+pytest --cov=src --cov-report=html --cov-fail-under=80
+```
+
+#### Universal Tools
+
+```bash
+# SonarQube (Multi-language)
+sonar-scanner
+
+# Git Hooks
+pre-commit run --all-files
+```
+
+---
+
+## 🏗️ Architecture Review
+
+### Module Dependency Analysis
+
+```markdown
+## Dependency Review Checklist
+
+### Circular Dependencies
+- [ ] No circular imports between modules
+- [ ] No bidirectional service calls
+- [ ] Dependency flow is unidirectional
+
+### Coupling Analysis
+| Module A | Module B | Coupling Type | Severity |
+|----------|----------|---------------|----------|
+| UserService | OrderService | Direct call | 🟡 Medium |
+| PaymentService | NotificationService | Event-based | ✅ Low |
+| AuthService | *All Services* | Shared | 🔴 High |
+```
+
+### Service Communication Patterns
+
+```markdown
+## Service Communication Review
+
+### REST API
+| Endpoint | Idempotent | Safe | Issues |
+|----------|------------|------|--------|
+| POST /orders | ❌ No | ❌ No | ⚠️ Need idempotency key |
+| PUT /orders/{id} | ✅ Yes | ❌ No | ✅ OK |
+| GET /orders/{id} | ✅ Yes | ✅ Yes | ✅ OK |
+| DELETE /orders/{id} | ✅ Yes | ❌ No | ⚠️ Soft delete? |
+
+### gRPC
+| Service | Method | Streaming | Timeout Set |
+|---------|--------|-----------|-------------|
+| UserService | GetUser | No | ✅ 5s |
+| OrderService | StreamOrders | Server | ⚠️ No timeout |
+```
+
+### Database Access Patterns
+
+```markdown
+## ORM/Database Review
+
+### N+1 Query Detection
+| Code Location | Pattern | Impact | Fix |
+|---------------|---------|--------|-----|
+| user_service.py:45 | Loop fetch | 100 users = 101 queries | Use JOIN/prefetch |
+| order_repo.py:78 | Lazy load | Each order triggers query | Eager load |
+
+### Transaction Boundaries
+| Operation | Isolation Level | Scope | Issues |
+|-----------|-----------------|-------|--------|
+| CreateOrder | Read Committed | Service | ✅ OK |
+| TransferFunds | Serializable | Repository | ⚠️ Deadlock risk |
+```
+
+---
+
+## 🔄 Concurrency Model Review
+
+### 1. Singleton vs Request Scope (CRITICAL)
+**Anti-Pattern**: Modifying shared singleton instances (Services, cached Models) with request-specific data.
+
+```python
+# ❌ DANGEROUS: Modifying shared agent object
+async def chat(self, user_input, llm_id=None):
+    # 'agent' is loaded once and shared across requests
+    if llm_id:
+        self.agent.llm_provider_id = llm_id  # RACE CONDITION! Affects other users
+    await self.executor.run(self.agent, user_input)
+
+# ✅ CORRECT: Pass request data as arguments
+async def chat(self, user_input, llm_id=None):
+    # Pass llm_id explicitly to the executor, don't mutate agent
+    await self.executor.run(self.agent, user_input, override_llm_id=llm_id)
+```
+
+### 2. Background Task Safety
+**Anti-Pattern**: Fire-and-forget tasks without error handling (Silent Failures).
+
+```python
+# ❌ Silent Failure
+asyncio.create_task(send_email())  # If fails, exception is swallowed/logged to void
+
+# ✅ With Exception Callback
+task = asyncio.create_task(send_email())
+def handle_error(t):
+    if not t.cancelled() and t.exception():
+        logger.error(f"Background task failed: {t.exception()}")
+task.add_done_callback(handle_error)
+
+# ✅ Or use TaskGroup (Python 3.11+)
+async with asyncio.TaskGroup() as tg:
+    tg.create_task(send_email())
+```
+
+### Java Thread Safety
+
+```java
+// ❌ Not thread-safe
+public class Counter {
+    private int count = 0;
+    public void increment() {
+        count++;  // Read-modify-write not atomic
+    }
+}
+
+// ✅ Thread-safe options
+public class Counter {
+    // Option 1: AtomicInteger
+    private final AtomicInteger count = new AtomicInteger(0);
+    public void increment() {
+        count.incrementAndGet();
+    }
+    
+    // Option 2: synchronized
+    private int count = 0;
+    public synchronized void increment() {
+        count++;
+    }
+}
+```
+
+### Go Goroutine Safety
+
+```go
+// ❌ Race condition
+var counter int
+func increment() {
+    counter++  // Not safe with multiple goroutines
+}
+
+// ✅ Use sync primitives
+var (
+    counter int
+    mu      sync.Mutex
+)
+func increment() {
+    mu.Lock()
+    defer mu.Unlock()
+    counter++
+}
+
+// ✅ Or use channels
+func counter(ch chan int) {
+    count := 0
+    for delta := range ch {
+        count += delta
+    }
+}
+```
+
+### Node.js Event Loop Blocking
+
+```typescript
+// ❌ Blocking the event loop
+app.get('/heavy', (req, res) => {
+    const result = heavyComputation();  // Blocks all requests!
+    res.json(result);
+});
+
+// ✅ Use worker threads for CPU-intensive tasks
+import { Worker } from 'worker_threads';
+
+app.get('/heavy', async (req, res) => {
+    const worker = new Worker('./heavy-worker.js');
+    worker.on('message', (result) => res.json(result));
+    worker.postMessage({ data: req.body });
+});
+```
+
+---
+
+## 📊 Runtime & Non-Functional Review
+
+### Load Testing Requirements
+
+```markdown
+## Performance Review Checklist
+
+### Load Testing Setup
+- [ ] Tool selected (JMeter/k6/Locust)
+- [ ] Test scenarios defined
+- [ ] Baseline metrics established
+
+### Key Metrics
+| Metric | Target | Actual | Status |
+|--------|--------|--------|--------|
+| P50 latency | <100ms | 85ms | ✅ |
+| P95 latency | <500ms | 620ms | ❌ |
+| P99 latency | <1s | 1.2s | ❌ |
+| Throughput | >1000 RPS | 950 RPS | ⚠️ |
+| Error rate | <0.1% | 0.05% | ✅ |
+
+### Bottleneck Analysis
+| Component | CPU | Memory | I/O | Issue |
+|-----------|-----|--------|-----|-------|
+| API Server | 45% | 60% | 10% | ✅ OK |
+| Database | 85% | 70% | 90% | 🔴 Bottleneck |
+| Cache | 20% | 80% | 5% | ⚠️ Memory pressure |
+```
+
+### Connection Pool Configuration
+
+```markdown
+## Connection Pool Review
+
+### Database Pool
+| Setting | Value | Recommendation | Status |
+|---------|-------|----------------|--------|
+| Min connections | 5 | 10 | ⚠️ Too low |
+| Max connections | 100 | 50-100 | ✅ OK |
+| Idle timeout | 30s | 60s | ⚠️ Adjust |
+| Max lifetime | None | 300s | ❌ Must set |
+| Acquire timeout | 5s | 10s | ✅ OK |
+
+### HTTP Client Pool
+| Setting | Value | Issue |
+|---------|-------|-------|
+| Max per route | 2 | 🔴 Default too low |
+| Max total | 20 | ⚠️ May be insufficient |
+| Connection timeout | 10s | ✅ OK |
+| Socket timeout | 30s | ✅ OK |
+```
+
+### Caching Strategy Review
+
+```markdown
+## Cache Review
+
+### Cache Configuration
+| Cache | Type | TTL | Eviction | Status |
+|-------|------|-----|----------|--------|
+| User sessions | Redis | 24h | LRU | ✅ |
+| API responses | Local | 5m | TTL | ✅ |
+| DB query cache | Redis | 1h | TTL | ⚠️ No invalidation |
+
+### Cache Issues Checklist
+- [ ] Cache penetration protection (bloom filter)
+- [ ] Cache avalanche prevention (jitter TTL)
+- [ ] Cache breakdown protection (mutex lock)
+- [ ] Cache warming strategy
+- [ ] Cache invalidation on write
+
+### Cache Penetration Example
+```python
+# ❌ No protection - null values not cached
+def get_user(user_id):
+    cached = redis.get(f"user:{user_id}")
+    if cached:
+        return cached
+    user = db.query(User).get(user_id)
+    if user:
+        redis.set(f"user:{user_id}", user, ex=3600)
+    return user  # Null not cached, repeated DB queries
+
+# ✅ Cache null values
+def get_user(user_id):
+    cached = redis.get(f"user:{user_id}")
+    if cached == "NULL":
+        return None
+    if cached:
+        return cached
+    user = db.query(User).get(user_id)
+    if user:
+        redis.set(f"user:{user_id}", user, ex=3600)
+    else:
+        redis.set(f"user:{user_id}", "NULL", ex=60)  # Short TTL for null
+    return user
+```
+```
+
+---
+
+## 📝 Observability Review
+
+### Structured Logging
+
+```markdown
+## Logging Review
+
+### Log Format Checklist
+- [ ] Structured format (JSON)
+- [ ] Correlation ID / Trace ID
+- [ ] Timestamp in ISO 8601
+- [ ] Log level appropriate
+- [ ] No sensitive data
+
+### Example: Proper Structured Log
+```json
+{
+  "timestamp": "2024-01-15T10:30:00.123Z",
+  "level": "INFO",
+  "service": "order-service",
+  "trace_id": "abc123",
+  "span_id": "def456",
+  "user_id": "user_789",
+  "action": "create_order",
+  "order_id": "order_001",
+  "duration_ms": 150,
+  "status": "success"
+}
+```
+
+### Log Level Guidelines
+| Level | Usage | Example |
+|-------|-------|---------|
+| ERROR | System failures requiring action | DB connection lost |
+| WARN | Potential issues, degraded service | Retry succeeded |
+| INFO | Business events, transactions | Order created |
+| DEBUG | Development/troubleshooting | Function entry/exit |
+```
+
+### Metrics & Tracing
+
+```markdown
+## Metrics Review
+
+### Required Metrics (RED Method)
+| Metric Type | Description | Implementation |
+|-------------|-------------|----------------|
+| Rate | Requests per second | Counter |
+| Errors | Error rate | Counter + Labels |
+| Duration | Response time distribution | Histogram |
+
+### Distributed Tracing Checklist
+- [ ] Trace ID propagated across services
+- [ ] Span context preserved in async calls
+- [ ] External calls instrumented
+- [ ] Database queries traced
+- [ ] Queue messages traced
+```
+
+---
+
+## 🔧 Configuration Management
+
+### Environment Variable Handling
+
+```python
+# ❌ No fallback, crashes on missing env
+import os
+API_KEY = os.environ["API_KEY"]
+
+# ❌ Silent failure, uses None
+API_KEY = os.environ.get("API_KEY")
+
+# ✅ Fail fast with clear message
+API_KEY = os.environ.get("API_KEY")
+if not API_KEY:
+    raise ValueError("API_KEY environment variable is required")
+
+# ✅ Use pydantic-settings for validation
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    api_key: str
+    database_url: str
+    debug: bool = False
+    
+    class Config:
+        env_file = ".env"
+
+settings = Settings()  # Fails fast with validation errors
+```
+
+### Graceful Shutdown
+
+```python
+# ❌ No graceful shutdown
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+# ✅ Graceful shutdown handler
+import signal
+import asyncio
+
+shutdown_event = asyncio.Event()
+
+def signal_handler(signum, frame):
+    shutdown_event.set()
+
+signal.signal(signal.SIGTERM, signal_handler)
+signal.signal(signal.SIGINT, signal_handler)
+
+@app.on_event("shutdown")
+async def shutdown():
+    # Complete in-flight requests
+    await shutdown_event.wait()
+    # Close connections
+    await db.disconnect()
+    await redis.close()
+```
+
+---
+
+## 🔄 Retry Mechanism Review
+
+### Exponential Backoff Pattern
+
+```python
+# ❌ Infinite retry without backoff
+def fetch_data(url):
+    while True:
+        try:
+            return requests.get(url).json()
+        except Exception:
+            continue  # Hammers the service!
+
+# ❌ Fixed delay retry
+def fetch_data(url):
+    for _ in range(3):
+        try:
+            return requests.get(url).json()
+        except Exception:
+            time.sleep(1)  # All retries hit at same time
+
+# ✅ Exponential backoff with jitter
+from tenacity import retry, stop_after_attempt, wait_exponential_jitter
+
+@retry(
+    stop=stop_after_attempt(5),
+    wait=wait_exponential_jitter(initial=1, max=30, jitter=5)
+)
+def fetch_data(url):
+    response = requests.get(url, timeout=10)
+    response.raise_for_status()
+    return response.json()
+```
+
+### Circuit Breaker Pattern
+
+```python
+from circuitbreaker import circuit
+
+@circuit(
+    failure_threshold=5,
+    recovery_timeout=60,
+    expected_exception=requests.RequestException
+)
+def call_external_service(url):
+    response = requests.get(url, timeout=10)
+    response.raise_for_status()
+    return response.json()
+```
+
+---
+
+## 🗄️ Database & Migration Review
+
+### Migration Safety Checklist
+
+```markdown
+## Migration Review
+
+### Pre-Deployment Checks
+- [ ] Migration tested on copy of production data
+- [ ] Rollback script exists and tested
+- [ ] Estimated execution time acceptable
+- [ ] No table locks on high-traffic tables
+- [ ] Backward compatible with current code
+
+### Schema Change Risk Matrix
+| Change Type | Risk Level | Strategy |
+|-------------|------------|----------|
+| Add nullable column | ✅ Low | Deploy migration, then code |
+| Add non-nullable column | 🟡 Medium | Add nullable → backfill → add constraint |
+| Drop column | 🟡 Medium | Remove code → deploy → drop column |
+| Rename column | 🔴 High | Add new → copy data → dual write → remove old |
+| Change column type | 🔴 High | Add new → copy → switch → remove |
+| Add index | 🟡 Medium | CONCURRENTLY if supported |
+| Drop table | 🔴 High | Verify no references → soft delete period |
+
+### Index Impact Analysis
+| Index | Table Size | Write Impact | Build Time |
+|-------|------------|--------------|------------|
+| idx_users_email | 1M rows | +5% | ~30s |
+| idx_orders_user_date | 10M rows | +15% | ~5min |
+```
+
+---
+
+## 🧪 Backend Test Review
+
+### Test Categories Checklist
+
+```markdown
+## Test Coverage Review
+
+### Unit Tests
+| Component | Coverage | Missing |
+|-----------|----------|---------|
+| Services | 85% | Error paths |
+| Repositories | 70% | Edge cases |
+| Utils | 95% | ✅ |
+
+### Integration Tests
+| Integration Point | Tested | Missing |
+|-------------------|--------|---------|
+| Database CRUD | ✅ | Transaction rollback |
+| Redis cache | ✅ | Cache invalidation |
+| External API | ⚠️ | Timeout handling |
+| Message queue | ❌ | All scenarios |
+
+### Contract Tests
+| API | Consumer | Provider | Status |
+|-----|----------|----------|--------|
+| /users | Frontend | Backend | ✅ |
+| /orders | Mobile | Backend | ⚠️ Drift |
+```
+
+### Mock Quality Review
+
+```python
+# ❌ Over-mocking - testing implementation not behavior
+@patch('myapp.services.user.repository.db.session.query')
+@patch('myapp.services.user.repository.db.session.add')
+@patch('myapp.services.user.repository.db.session.commit')
+def test_create_user(mock_commit, mock_add, mock_query):
+    # Testing implementation details, not behavior
+
+# ✅ Mock at boundaries only
+@patch('myapp.services.external_api.verify_email')
+def test_create_user(mock_verify):
+    mock_verify.return_value = True
+    result = UserService.create(valid_user_data)
+    assert result.email_verified is True
+    mock_verify.assert_called_once_with(valid_user_data.email)
+```
+
+---
+
+## 📋 Backend Review Summary Template
+
+```markdown
+# Backend Review Report
+
+## Coverage Summary
+| Category | Files | Reviewed | Issues |
+|----------|-------|----------|--------|
+| Controllers/Routes | X | X | N |
+| Services | X | X | N |
+| Repositories | X | X | N |
+| Models | X | X | N |
+| Utils | X | X | N |
+| Config | X | X | N |
+| Migrations | X | X | N |
+| Tests | X | X | N |
+
+## Tool Scan Results
+| Tool | Status | Critical | Warning |
+|------|--------|----------|---------|
+| Linter | ✅ | 0 | 5 |
+| Type Check | ✅ | 0 | 2 |
+| Security Scan | ⚠️ | 1 | 3 |
+| Coverage | ❌ | 75% (<80%) | - |
+
+## Architecture Issues
+| Issue | Severity | Location | Recommendation |
+|-------|----------|----------|----------------|
+| Circular import | 🟡 | service A ↔ B | Extract shared interface |
+| N+1 query | 🔴 | repo.py:45 | Use select_related |
+
+## Runtime Concerns
+| Concern | Status | Action Required |
+|---------|--------|-----------------|
+| Connection pool | ⚠️ | Increase max connections |
+| Cache strategy | ❌ | Add cache invalidation |
+| Error handling | ⚠️ | Add retry with backoff |
+
+## Security Findings
+| Finding | Severity | Location | Fix |
+|---------|----------|----------|-----|
+| SQL injection risk | 🔴 Critical | query.py:23 | Use parameterized query |
+| Hardcoded secret | 🔴 Critical | config.py:5 | Move to env var |
+
+## Recommendations
+1. **[P0]** Fix SQL injection vulnerability before merge
+2. **[P1]** Add missing integration tests
+3. **[P2]** Implement circuit breaker for external calls
+4. **[P3]** Consider adding request tracing
+```
+
+---
+
+## 🔐 Comprehensive Security Review Checklist
+
+Detailed security checks beyond OWASP basics. Use this for any code touching auth, data, or external input.
+
+### Authentication & Authorization
+
+```markdown
+## Auth Security Checklist
+
+### Authentication
+- [ ] JWT validation includes BOTH signature AND expiry check
+- [ ] Password hashing uses bcrypt (cost >= 10) or argon2
+- [ ] API keys are not hardcoded in source
+- [ ] Session tokens have appropriate expiry
+- [ ] Failed login attempts are rate-limited
+- [ ] Password reset tokens are single-use and time-limited
+
+### Authorization
+- [ ] Every state-changing endpoint has authorization check
+- [ ] Authorization happens BEFORE business logic
+- [ ] Resource ownership verified (user can only access their data)
+- [ ] Role/permission checks use allowlist, not denylist
+- [ ] Admin endpoints have additional authentication factor
+
+### Session Management
+- [ ] Sessions invalidated on password change
+- [ ] Sessions invalidated on logout
+- [ ] Session tokens regenerated after privilege escalation
+- [ ] Concurrent session limit enforced (if applicable)
+```
+
+### Input Validation & Sanitization
+
+```markdown
+## Input Security Checklist
+
+### Request Validation
+- [ ] All user inputs validated on server side
+- [ ] Input length limits enforced
+- [ ] Input type validation (string, number, email, etc.)
+- [ ] Whitelist allowed characters where applicable
+- [ ] File uploads restricted by size AND type
+- [ ] File upload names sanitized
+
+### Injection Prevention
+- [ ] SQL queries use parameterized statements (NEVER string concat)
+- [ ] NoSQL queries use typed queries (not $where)
+- [ ] Shell commands use subprocess with list args (not shell=True)
+- [ ] LDAP queries use proper escaping
+- [ ] XML parsing disables external entities (XXE prevention)
+
+### Output Encoding
+- [ ] HTML output escaped (XSS prevention)
+- [ ] JSON responses use proper Content-Type
+- [ ] Error messages don't leak internal details
+- [ ] Stack traces not exposed to users
+```
+
+### Data Protection
+
+```markdown
+## Data Security Checklist
+
+### Storage Security
+- [ ] Passwords NEVER stored in plaintext
+- [ ] Sensitive data encrypted at rest
+- [ ] Encryption keys stored separately from data
+- [ ] PII handled per compliance requirements (GDPR, etc.)
+- [ ] Credit card data follows PCI-DSS
+
+### Transport Security
+- [ ] HTTPS enforced for all sensitive endpoints
+- [ ] HSTS header enabled
+- [ ] Secure cookies (Secure, HttpOnly, SameSite)
+- [ ] Certificate validation not disabled
+
+### Logging Security
+- [ ] Passwords/tokens NEVER logged
+- [ ] PII redacted from logs
+- [ ] Request bodies sanitized before logging
+- [ ] Log injection prevented (newline characters)
+```
+
+### Common Vulnerability Patterns
+
+```python
+# 🚫 SQL Injection
+query = f"SELECT * FROM users WHERE id = {user_id}"  # 💀
+
+# ✅ Parameterized query
+cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+
+# 🚫 Command Injection
+os.system(f"convert {user_filename} output.png")  # 💀
+
+# ✅ Safe subprocess
+subprocess.run(["convert", user_filename, "output.png"])
+
+# 🚫 Path Traversal
+file_path = f"/uploads/{user_filename}"  # 💀 User can pass ../../../etc/passwd
+
+# ✅ Path validation
+safe_path = Path("/uploads") / user_filename
+if not safe_path.resolve().is_relative_to(Path("/uploads").resolve()):
+    raise ValueError("Invalid path")
+
+# 🚫 Hardcoded secret
+API_KEY = "sk-prod-abc123xyz"  # 💀 Visible in git history forever
+
+# ✅ Environment variable
+API_KEY = os.environ["API_KEY"]  # With validation
+
+# 🚫 Insecure random
+token = str(random.randint(0, 999999))  # 💀 Predictable
+
+# ✅ Cryptographic random
+token = secrets.token_urlsafe(32)
+
+# 🚫 Missing rate limit
+@app.post("/login")  # 💀 Brute force possible
+def login(credentials): ...
+
+# ✅ Rate limited
+@app.post("/login")
+@limiter.limit("5/minute")
+def login(credentials): ...
+```
+
+### Security Detection Commands
+
+```bash
+# Find hardcoded secrets
+grep -rn "password\s*=\|api_key\s*=\|secret\s*=" --include="*.py" --include="*.ts" | grep -v "os.environ\|process.env\|config\."
+
+# Find SQL string concatenation
+grep -rn "SELECT.*+.*user\|INSERT.*+.*user\|UPDATE.*+.*user" --include="*.py" --include="*.ts"
+
+# Find shell=True usage (Python)
+grep -rn "shell=True" --include="*.py"
+
+# Find eval/exec usage
+grep -rn "\beval(\|exec(" --include="*.py" --include="*.ts" --include="*.js"
+
+# Find disabled SSL verification
+grep -rn "verify=False\|rejectUnauthorized.*false" --include="*.py" --include="*.ts"
+```
+