@tinkcarlos/skillora 0.2.0

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

@@ -0,0 +1,477 @@
+# Full-Stack Review Guide
+
+Comprehensive guide for reviewing projects with both frontend and backend code.
+
+---
+
+## Full-Stack Project Detection
+
+### Directory Structure Indicators
+
+```
+# Monorepo Structure
+project/
+├── frontend/          # or client/, web/, app/
+├── backend/           # or server/, api/
+└── shared/            # or common/, types/
+
+# Package Structure
+project/
+├── packages/
+│   ├── client/
+│   ├── server/
+│   └── shared/
+
+# Single Repo with Mixed
+project/
+├── src/
+│   ├── client/
+│   ├── server/
+│   └── shared/
+```
+
+### File Type Indicators
+
+| Stack | File Patterns |
+|-------|---------------|
+| Frontend | `.tsx`, `.jsx`, `.vue`, `.svelte`, `component.ts` |
+| Backend Python | `.py`, `views.py`, `routes.py`, `services.py` |
+| Backend Node | `.ts` in `/api/`, `/routes/`, `/controllers/` |
+| Shared | `/shared/`, `/common/`, `/types/` |
+
+---
+
+## Mandatory Full-Stack Review Rules
+
+### Rule 1: Backend API Change → Review Frontend Consumers
+
+```
+Backend Change: POST /api/users response changed
+    ↓
+MUST REVIEW:
+- All frontend files that call POST /api/users
+- All components that display user data
+- All stores/state that cache user data
+```
+
+### Rule 2: Frontend API Call Change → Review Backend Endpoint
+
+```
+Frontend Change: Added new API call to /api/settings
+    ↓
+MUST REVIEW:
+- Backend endpoint /api/settings exists
+- Request payload matches backend expectation
+- Response handling matches backend response
+- Error handling covers all backend error codes
+```
+
+### Rule 3: New Feature → Review Entire Stack
+
+```
+New Feature: User Profile Edit
+    ↓
+MUST REVIEW:
+- Backend: Model, Repository, Service, Controller, Routes
+- Frontend: Component, Hook/Store, API call, Types
+- Shared: Types, Validation schemas
+- Tests: Backend unit, Frontend unit, Integration
+```
+
+### Rule 4: Shared Types Change → Verify Both Sides
+
+```
+Shared Type Change: User interface updated
+    ↓
+MUST VERIFY:
+- Backend serialization matches new type
+- Frontend deserialization handles new fields
+- All consumers updated
+- Migrations in place for DB changes
+```
+
+### Rule 5: Auth Change → Full Security Review
+
+```
+Auth Change: Any auth-related code
+    ↓
+MUST REVIEW:
+- Backend: Token generation, validation, refresh
+- Backend: Permission checks, middleware
+- Frontend: Token storage, transmission
+- Frontend: Route guards, permission checks
+- Full Flow: Login → Action → Logout
+```
+
+---
+
+## API Contract Verification Template
+
+### For Each Endpoint
+
+```markdown
+## Endpoint: [METHOD] [PATH]
+
+### Request Contract
+
+#### Backend Definition
+```python
+# FastAPI example
+class CreateUserRequest(BaseModel):
+    email: str = Field(..., regex=r'^[\w\.-]+@[\w\.-]+\.\w+$')
+    password: str = Field(..., min_length=8)
+    name: Optional[str] = Field(None, max_length=100)
+```
+
+#### Frontend Definition
+```typescript
+interface CreateUserRequest {
+  email: string;
+  password: string;
+  name?: string;
+}
+```
+
+#### Contract Comparison
+| Field | Backend | Frontend | Match |
+|-------|---------|----------|-------|
+| email | str, required, email regex | string, required | ⚠️ No regex validation |
+| password | str, required, min 8 | string, required | ⚠️ No min length |
+| name | Optional[str], max 100 | string?, no limit | ⚠️ No max length |
+
+### Response Contract
+
+#### Success Response (200)
+| Field | Backend | Frontend | Match |
+|-------|---------|----------|-------|
+| id | str (UUID) | string | ✅ |
+| email | str | string | ✅ |
+| created_at | datetime (ISO) | string (Date) | ⚠️ Parsing needed |
+
+#### Error Responses
+| Status | Backend Error | Frontend Handler | Coverage |
+|--------|---------------|------------------|----------|
+| 400 | ValidationError | Shows field errors | ✅ |
+| 401 | Unauthorized | Redirects to login | ✅ |
+| 403 | Forbidden | Shows access denied | ✅ |
+| 404 | NotFound | Shows not found | ✅ |
+| 409 | Conflict (email exists) | Shows specific error | ❌ Missing |
+| 422 | UnprocessableEntity | Shows generic error | ⚠️ Generic |
+| 429 | RateLimited | No handler | ❌ Missing |
+| 500 | ServerError | Shows retry option | ✅ |
+```
+
+---
+
+## Type Synchronization Guide
+
+### Python (Pydantic) ↔ TypeScript
+
+```python
+# Backend: Python Pydantic
+from datetime import datetime
+from typing import Optional, List
+from pydantic import BaseModel
+from enum import Enum
+
+class UserRole(str, Enum):
+    ADMIN = "admin"
+    USER = "user"
+
+class User(BaseModel):
+    id: str
+    email: str
+    name: Optional[str]
+    role: UserRole
+    created_at: datetime
+    tags: List[str]
+```
+
+```typescript
+// Frontend: TypeScript
+type UserRole = 'admin' | 'user';
+
+interface User {
+  id: string;
+  email: string;
+  name: string | null;  // ⚠️ Optional vs null
+  role: UserRole;
+  createdAt: string;    // ⚠️ Naming convention
+  tags: string[];
+}
+```
+
+### Common Sync Issues
+
+| Issue | Backend | Frontend | Solution |
+|-------|---------|----------|----------|
+| Naming convention | `snake_case` | `camelCase` | Use serializer/transformer |
+| Optional handling | `Optional[T]` | `T \| null` or `T?` | Document convention |
+| Date format | `datetime` | `string` or `Date` | Parse on frontend |
+| Enum | Python Enum | Union type | Keep values synced |
+| ID type | UUID string | string | Consistent typing |
+
+### Type Generation Tools
+
+```bash
+# Generate TypeScript from Python (FastAPI)
+pip install datamodel-code-generator
+datamodel-codegen --input openapi.json --output types.ts
+
+# Generate from OpenAPI
+npx openapi-typescript openapi.yaml --output types.ts
+
+# Keep in sync with JSON Schema
+```
+
+---
+
+## Data Flow Verification
+
+### Template: Feature Flow
+
+```markdown
+## Feature: [Name]
+
+### User Journey
+1. User navigates to [page]
+2. User fills [form/interacts]
+3. System [action]
+4. User sees [result]
+
+### Technical Flow
+
+```
+[Frontend Entry Point]
+    ↓
+Page: src/pages/Feature.tsx
+    ↓ User clicks action
+Component: src/components/FeatureForm.tsx
+    ↓ handleSubmit()
+Hook: src/hooks/useFeature.ts
+    ↓ mutation.mutate(data)
+API Client: src/api/feature.ts
+    ↓ POST /api/feature { payload }
+────────── NETWORK ──────────
+    ↓
+Router: backend/routes/feature.py
+    ↓ Middleware: auth, validation
+Controller: backend/controllers/feature.py
+    ↓ Business logic validation
+Service: backend/services/feature.py
+    ↓ Domain logic
+Repository: backend/repos/feature.py
+    ↓ Database operation
+Database: Feature table
+    ↓ Return result
+────────── RETURN ──────────
+    ↓
+API Client: Parse response
+    ↓
+Hook: Update cache/state
+    ↓
+Component: Re-render with new data
+    ↓
+User: Sees success message
+```
+
+### Verification Checklist
+
+| Step | Component | Verified | Issues |
+|------|-----------|----------|--------|
+| 1 | Page routing | ✅ | - |
+| 2 | Form validation | ⚠️ | Missing email check |
+| 3 | API call | ✅ | - |
+| 4 | Auth middleware | ✅ | - |
+| 5 | Input validation | ⚠️ | Differs from frontend |
+| 6 | Business logic | ✅ | - |
+| 7 | Database operation | ✅ | - |
+| 8 | Response format | ✅ | - |
+| 9 | Error handling | ❌ | Missing 409 handler |
+| 10 | State update | ✅ | - |
+| 11 | UI feedback | ⚠️ | No loading state |
+```
+
+---
+
+## Security Review (Full-Stack)
+
+### Authentication Flow
+
+```markdown
+## Auth Flow Review
+
+### Token Generation (Backend)
+| Check | Status | Notes |
+|-------|--------|-------|
+| Strong secret | ✅ | From env, 256+ bits |
+| Appropriate expiry | ⚠️ | 24h (too long?) |
+| Necessary claims only | ✅ | id, role only |
+| No sensitive data in token | ✅ | - |
+
+### Token Storage (Frontend)
+| Check | Status | Notes |
+|-------|--------|-------|
+| httpOnly cookie | ❌ | Using localStorage |
+| Secure flag | N/A | (if cookie) |
+| SameSite flag | N/A | (if cookie) |
+| XSS protection | ⚠️ | localStorage vulnerable |
+
+### Token Transmission
+| Check | Status | Notes |
+|-------|--------|-------|
+| HTTPS only | ✅ | Enforced |
+| Authorization header | ✅ | Bearer token |
+| No token in URL | ✅ | - |
+
+### Session Management
+| Check | Status | Notes |
+|-------|--------|-------|
+| Token refresh | ✅ | Implemented |
+| Logout invalidation | ❌ | Token still valid |
+| Concurrent sessions | ⚠️ | No limit |
+```
+
+### Authorization Review
+
+```markdown
+## Authorization Review
+
+### Backend Checks
+| Resource | Method | Auth Required | Permission Check | Status |
+|----------|--------|---------------|------------------|--------|
+| /users | GET | ✅ | admin only | ✅ |
+| /users/:id | GET | ✅ | owner or admin | ✅ |
+| /users/:id | PUT | ✅ | owner only | ✅ |
+| /users/:id | DELETE | ✅ | admin only | ✅ |
+| /settings | GET | ✅ | any user | ⚠️ No check |
+
+### Frontend Guards
+| Route | Auth Guard | Role Guard | Status |
+|-------|------------|------------|--------|
+| /admin/* | ✅ | ✅ admin | ✅ |
+| /profile | ✅ | - | ✅ |
+| /settings | ✅ | - | ✅ |
+| /public | - | - | ✅ |
+| /api-docs | ❌ | - | 🔴 Should protect |
+```
+
+---
+
+## Common Full-Stack Issues
+
+### 1. API Contract Mismatch
+
+```
+Issue: Frontend sends camelCase, backend expects snake_case
+Fix: Add request/response transformer
+```
+
+### 2. Missing Error Handler
+
+```
+Issue: Backend returns 409 Conflict, frontend shows generic error
+Fix: Add specific error handler for 409
+```
+
+### 3. Type Drift
+
+```
+Issue: Backend adds field, frontend type not updated
+Fix: Generate types from OpenAPI, add to CI
+```
+
+### 4. Auth State Desync
+
+```
+Issue: Backend invalidates token, frontend still shows logged in
+Fix: Add token validation on app load
+```
+
+### 5. Validation Mismatch
+
+```
+Issue: Frontend allows input, backend rejects
+Fix: Share validation rules or generate from schema
+```
+
+### 6. Timezone Issues
+
+```
+Issue: Backend returns UTC, frontend displays wrong time
+Fix: Standardize on UTC, convert on display
+```
+
+### 7. Pagination Mismatch
+
+```
+Issue: Backend uses offset/limit, frontend expects page/size
+Fix: Align pagination parameters
+```
+
+### 8. File Upload Issues
+
+```
+Issue: Frontend sends multipart, backend expects JSON
+Fix: Align content types and handlers
+```
+
+---
+
+## Full-Stack Review Checklist
+
+### Before Merge
+
+- [ ] All backend files reviewed (100%)
+- [ ] All frontend files reviewed (100%)
+- [ ] API contracts verified for all endpoints
+- [ ] Types synchronized across stack
+- [ ] Error handling covers all status codes
+- [ ] Auth flow verified end-to-end
+- [ ] CORS configured correctly
+- [ ] CSRF protection in place
+- [ ] Input validation aligned
+- [ ] Response format consistent
+- [ ] Tests exist for integration points
+
+### Integration Test Scenarios
+
+- [ ] Happy path works end-to-end
+- [ ] Auth failure handled gracefully
+- [ ] Network error handled
+- [ ] Validation error displayed
+- [ ] Empty state displayed
+- [ ] Loading state displayed
+- [ ] Concurrent requests handled
+- [ ] Token refresh works
+- [ ] Logout clears all state
+
+---
+
+## Review Report Full-Stack Section
+
+```markdown
+## Full-Stack Integration Summary
+
+### Coverage
+| Stack | Files | Reviewed | Issues |
+|-------|-------|----------|--------|
+| Backend | X | X (100%) | N |
+| Frontend | Y | Y (100%) | M |
+| Integration | Z | Z (100%) | O |
+
+### API Contract Status
+| Endpoint | Backend | Frontend | Contract | Issues |
+|----------|---------|----------|----------|--------|
+| POST /login | ✅ | ✅ | ✅ | 0 |
+| GET /users | ✅ | ✅ | ⚠️ | 1 (type) |
+
+### Critical Integration Issues
+1. [Issue 1 with file references]
+2. [Issue 2 with file references]
+
+### Recommendations
+1. [Recommendation 1]
+2. [Recommendation 2]
+```
+